:program: markup in .rst documentation
While fixing the :option: markup in the library docs (http://bugs.python.org/issue9312), another question came up: In a few places, documenting a program execution with options was made with: :program:`python regrtest.py` :option:`test_spam.py` Since my patch had the :option: markup removed, this became: :program:`python regrtest.py test_spam.py` However, according to Éric Araujo's comment, due to the intention of the :program: markup this should actually just say: ``python regrtest.py test_spam.py`` Which way to choose? I will update my patch to reflect this. Eli
On Tue, Jul 20, 2010 at 1:16 PM, Eli Bendersky <eliben@gmail.com> wrote: ..
``python regrtest.py test_spam.py``
Which way to choose? I will update my patch to reflect this.
Sorry to add the third way to the mix, but shouldn't the recommended way to run a module as a script be python -m modname? As in $ python -m test.regrtest test_spam
Switching to "python -m" is generally good where it applies (as in this case). The original intent for :option: and :program: were in their use as references rather than in sample command lines. Georg should be the final arbiter, but I'd be in favor of ``...`` for command lines.
Sorry to add the third way to the mix, but shouldn't the recommended way to run a module as a script be python -m modname? As in
$ python -m test.regrtest test_spam
This is true but orthogonal to our problem, which is that :program:`python -m thing` is wrong if I understood the doc rightly and should be replaced by ``python -m thing``. Regards
On Tue, Jul 20, 2010 at 20:34, Éric Araujo <merwok@netwok.org> wrote:
Sorry to add the third way to the mix, but shouldn't the recommended way to run a module as a script be python -m modname? As in
$ python -m test.regrtest test_spam
This is true but orthogonal to our problem, which is that :program:`python -m thing` is wrong if I understood the doc rightly and should be replaced by ``python -m thing``.
So, how can a decision be reached on this issue? I'd like to fix the relevant docs because currently there's a lot of confusion. I will fix the :program: markup together with all the :option: and :cmdoption: markup. Eli
On Thu, Jul 22, 2010 at 11:25 AM, Eli Bendersky <eliben@gmail.com> wrote:
.. shouldn't the recommended way to run a module as a script be python -m modname? As in
$ python -m test.regrtest test_spam .. So, how can a decision be reached on this issue? I'd like to fix the relevant docs because currently there's a lot of confusion. I will fix the :program: markup together with all the :option: and :cmdoption: markup.
Note also that argparse/optparse does not know about -m way either: $ python -m profile -h Usage: profile.py [-o output_file_path] [-s sort] scriptfile [arg] ... I am not sure if it is possible for argparse to distinguish between -m and file name invocations, so maybe it should always use python -m modname if sys.argv[0] ends with .py. Again, this is quite important if the module being run is inside a package.
On Fri, Jul 23, 2010 at 2:25 AM, Alexander Belopolsky <alexander.belopolsky@gmail.com> wrote:
Note also that argparse/optparse does not know about -m way either:
$ python -m profile -h Usage: profile.py [-o output_file_path] [-s sort] scriptfile [arg] ...
I am not sure if it is possible for argparse to distinguish between -m and file name invocations, so maybe it should always use python -m modname if sys.argv[0] ends with .py. Again, this is quite important if the module being run is inside a package.
If __main__.__package__ is set to anything other than None, odds are fairly good that runpy did the import. If it's set to a non-empty string, you definitely *shouldn't* be invoking the relevant main script by filename. Sounds like one for the tracker. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
Am 20.07.2010 19:32, schrieb Fred Drake:
Switching to "python -m" is generally good where it applies (as in this case).
The original intent for :option: and :program: were in their use as references rather than in sample command lines.
Georg should be the final arbiter, but I'd be in favor of ``...`` for command lines.
Agreed. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.
participants (6)
-
Alexander Belopolsky -
Eli Bendersky -
Fred Drake -
Georg Brandl -
Nick Coghlan -
Éric Araujo