Markup of command-line options in Python's .rst documentation
Hello, I'm currently working, together with Terry Reedy, on improving the documentation of the trace module, and I ran into a peculiar convention of marking command-line options which seems to be widespread. Consider the documentation of timeit, for instance: http://docs.python.org/dev/py3k/library/timeit.html The "--help" option appears as a hyperlink leading to http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is hardly relevant or useful. The same applies for several command-line options documented for the trace module (for example -m and -s). This is a result of the following markup (again, taking the timeit module as an example) in the relevant .rst file (Doc/library/timeit.rst): -h/:option:`--help` print a short usage message and exit The :option: markup seems to be translated by Sphinx into a link to the Python executable's own command line arguments. This creates the aforementioned problem in other modules as well, for example unittest. Is there really any merit in marking command-line options for modules with :option:, if it's only useful for Python's own options? Eli
On 17/07/2010 14:23, Eli Bendersky wrote:
Hello,
I'm currently working, together with Terry Reedy, on improving the documentation of the trace module, and I ran into a peculiar convention of marking command-line options which seems to be widespread.
Consider the documentation of timeit, for instance: http://docs.python.org/dev/py3k/library/timeit.html
The "--help" option appears as a hyperlink leading to http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is hardly relevant or useful.
The same applies for several command-line options documented for the trace module (for example -m and -s). This is a result of the following markup (again, taking the timeit module as an example) in the relevant .rst file (Doc/library/timeit.rst):
-h/:option:`--help` print a short usage message and exit
The :option: markup seems to be translated by Sphinx into a link to the Python executable's own command line arguments. This creates the aforementioned problem in other modules as well, for example unittest. Is there really any merit in marking command-line options for modules with :option:, if it's only useful for Python's own options?
If it links to the wrong thing then the markup is incorrect (unless it is due to a regression in Sphinx but I think that is unlikely). Michael
Eli
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.u...
-- http://www.ironpythoninaction.com/ http://www.voidspace.org.uk/blog READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies ("BOGUS AGREEMENTS") that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.
On Sat, Jul 17, 2010 at 16:26, Michael Foord <fuzzyman@voidspace.org.uk>wrote:
On 17/07/2010 14:23, Eli Bendersky wrote:
Hello,
I'm currently working, together with Terry Reedy, on improving the documentation of the trace module, and I ran into a peculiar convention of marking command-line options which seems to be widespread.
Consider the documentation of timeit, for instance: http://docs.python.org/dev/py3k/library/timeit.html
The "--help" option appears as a hyperlink leading to http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is hardly relevant or useful.
The same applies for several command-line options documented for the trace module (for example -m and -s). This is a result of the following markup (again, taking the timeit module as an example) in the relevant .rst file (Doc/library/timeit.rst):
-h/:option:`--help` print a short usage message and exit
The :option: markup seems to be translated by Sphinx into a link to the Python executable's own command line arguments. This creates the aforementioned problem in other modules as well, for example unittest. Is there really any merit in marking command-line options for modules with :option:, if it's only useful for Python's own options?
If it links to the wrong thing then the markup is incorrect (unless it is due to a regression in Sphinx but I think that is unlikely).
Michael
Michael, What *should* it link to in case of modules, however? Is there some streamlined policy as to how module command line options should look and where they should be listed? From a cursory look on some documentation files, it's unlikely. Perhaps the answer is not to markup module options with :option: at all, because it's reserved for Python's own command-line options. Eli
On 17/07/2010 14:44, Eli Bendersky wrote:
On Sat, Jul 17, 2010 at 16:26, Michael Foord <fuzzyman@voidspace.org.uk <mailto:fuzzyman@voidspace.org.uk>> wrote:
On 17/07/2010 14:23, Eli Bendersky wrote:
Hello,
I'm currently working, together with Terry Reedy, on improving the documentation of the trace module, and I ran into a peculiar convention of marking command-line options which seems to be widespread.
Consider the documentation of timeit, for instance: http://docs.python.org/dev/py3k/library/timeit.html
The "--help" option appears as a hyperlink leading to http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is hardly relevant or useful.
The same applies for several command-line options documented for the trace module (for example -m and -s). This is a result of the following markup (again, taking the timeit module as an example) in the relevant .rst file (Doc/library/timeit.rst):
-h/:option:`--help` print a short usage message and exit
The :option: markup seems to be translated by Sphinx into a link to the Python executable's own command line arguments. This creates the aforementioned problem in other modules as well, for example unittest. Is there really any merit in marking command-line options for modules with :option:, if it's only useful for Python's own options?
If it links to the wrong thing then the markup is incorrect (unless it is due to a regression in Sphinx but I think that is unlikely).
Michael
Michael, What *should* it link to in case of modules, however? Is there some streamlined policy as to how module command line options should look and where they should be listed? From a cursory look on some documentation files, it's unlikely.
Perhaps the answer is not to markup module options with :option: at all, because it's reserved for Python's own command-line options.
:option: is "reserved" for Python command line options so *shouldn't* be used for module options. We don't have specific markup for module options, so just ``code`` markup I guess. Michael
Eli
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.u...
The "--help" option appears as a hyperlink leading to http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is hardly relevant or useful. [...]
-h/:option:`--help` print a short usage message and exit
I think this is a doc bug in Doc/documenting/markup.rst :cmdoption: and :option: are not clearly distinguished; the latter creates references to using/cmdline, the former is what you’re looking for for documenting trace.py. Regards
On Sat, Jul 17, 2010 at 16:44, Éric Araujo <merwok@netwok.org> wrote:
The "--help" option appears as a hyperlink leading to http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is hardly relevant or useful. [...]
-h/:option:`--help` print a short usage message and exit
I think this is a doc bug in Doc/documenting/markup.rst :cmdoption: and :option: are not clearly distinguished; the latter creates references to using/cmdline, the former is what you’re looking for for documenting trace.py.
How would you guys recommend to proceed from here? The simplest approach for me is just use :cmdoption: instead of :option: in my work on trace.py . However, a few more things can be done if this is indeed "official policy": 1. Fix other modules that use :option: to use :cmdoption: instead (timeit, unittest and others) 2. Fix Doc/documenting/markup.rst to clarify which option kind goes where If these steps get approved I'll be happy to create an issue and submit patches to the relevant files. Eli
On Mon, Jul 19, 2010 at 05:57, Eli Bendersky <eliben@gmail.com> wrote:
On Sat, Jul 17, 2010 at 16:44, Éric Araujo <merwok@netwok.org> wrote:
The "--help" option appears as a hyperlink leading to http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is hardly relevant or useful. [...]
-h/:option:`--help` print a short usage message and exit
I think this is a doc bug in Doc/documenting/markup.rst :cmdoption: and :option: are not clearly distinguished; the latter creates references to using/cmdline, the former is what you’re looking for for documenting trace.py.
How would you guys recommend to proceed from here?
The simplest approach for me is just use :cmdoption: instead of :option: in my work on trace.py . However, a few more things can be done if this is indeed "official policy":
1. Fix other modules that use :option: to use :cmdoption: instead (timeit, unittest and others) 2. Fix Doc/documenting/markup.rst to clarify which option kind goes where
If these steps get approved I'll be happy to create an issue and submit patches to the relevant files.
Eli
More input on this issue: 'cmdoption' is a directive, while 'option' is inline markup. Therefore I wouldn't say they're completely similar, just meant for different purposes. Both a directive and inline markup is useful for describing "official python executable options/flags". Regarding per-module options, I'm not sure special markup is needed at all. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst Eli
On Sun, Jul 18, 2010 at 11:28 PM, Eli Bendersky <eliben@gmail.com> wrote:
.. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst
I wonder if in addition to documenting proper markup you could add an option to argparse to generate help in ReST format. I understand that this will not be immediately useful for trace.py which uses getopt and getopt does not have enough structured data to generate good help. On the other hand, upgrading trace.py to use argparse may not be a bad idea.
On Mon, Jul 19, 2010 at 06:40, Alexander Belopolsky < alexander.belopolsky@gmail.com> wrote:
On Sun, Jul 18, 2010 at 11:28 PM, Eli Bendersky <eliben@gmail.com> wrote:
.. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst
I wonder if in addition to documenting proper markup you could add an option to argparse to generate help in ReST format. I understand that this will not be immediately useful for trace.py which uses getopt and getopt does not have enough structured data to generate good help. On the other hand, upgrading trace.py to use argparse may not be a bad idea.
I actually considered switching to argparse when I noticed that trace.py still lives with getopt (personally I've long been using optparse). However, I wonder what this means for backwards compatibility. Is it valid to switch trace.py to use the newer command-line argument parsing module that's only available in the newest versions of Python? I guess it could be since trace.py is stdlib which always arrives with its relevant version of Python. This *would* mean, however, that trace.py would be incompatible between 2.7 (argparse) and 2.6 (which doesn't have argparse), but I'm not sure how much of a problem this is. Eli
On Sun, Jul 18, 2010 at 11:46 PM, Eli Bendersky <eliben@gmail.com> wrote: ..
However, I wonder what this means for backwards compatibility. Is it valid to switch trace.py to use the newer command-line argument parsing module that's only available in the newest versions of Python? I guess it could be since trace.py is stdlib which always arrives with its relevant version of Python. This *would* mean, however, that trace.py would be incompatible between 2.7 (argparse) and 2.6 (which doesn't have argparse), but I'm not sure how much of a problem this is.
As long as 3.x trace supports all command line options and switches that 2.x does, I don't see any compatibility problems. Adding more options or using new language or library features in implementation should be fine.
Am 19.07.2010 04:28, schrieb Eli Bendersky:
On Mon, Jul 19, 2010 at 05:57, Eli Bendersky <eliben@gmail.com <mailto:eliben@gmail.com>> wrote:
On Sat, Jul 17, 2010 at 16:44, Éric Araujo <merwok@netwok.org <mailto:merwok@netwok.org>> wrote:
> The "--help" option appears as a hyperlink leading to > http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help, which is > hardly relevant or useful. [...] > > -h/:option:`--help` > print a short usage message and exit
I think this is a doc bug in Doc/documenting/markup.rst :cmdoption: and :option: are not clearly distinguished; the latter creates references to using/cmdline, the former is what you’re looking for for documenting trace.py.
How would you guys recommend to proceed from here?
The simplest approach for me is just use :cmdoption: instead of :option: in my work on trace.py . However, a few more things can be done if this is indeed "official policy":
1. Fix other modules that use :option: to use :cmdoption: instead (timeit, unittest and others) 2. Fix Doc/documenting/markup.rst to clarify which option kind goes where
If these steps get approved I'll be happy to create an issue and submit patches to the relevant files.
Eli
More input on this issue:
'cmdoption' is a directive, while 'option' is inline markup. Therefore I wouldn't say they're completely similar, just meant for different purposes. Both a directive and inline markup is useful for describing "official python executable options/flags". Regarding per-module options, I'm not sure special markup is needed at all. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst
I've done that now in r82961. 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.
More input on this issue:
'cmdoption' is a directive, while 'option' is inline markup. Therefore I wouldn't say they're completely similar, just meant for different
purposes. Both
a directive and inline markup is useful for describing "official python executable options/flags". Regarding per-module options, I'm not sure special markup is needed at all. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst
I've done that now in r82961.
Georg
Georg, Your fix indeed clarifies :option:. However, I think that cmdoption could also be made clearer by re-iterating that it is to refer to Python's own options only, and not to be used for command line options of modules. Eli
'cmdoption' is a directive, while 'option' is inline markup. Therefore I wouldn't say they're completely similar, just meant for different purposes. Both a directive and inline markup is useful for describing "official python executable options/flags". Regarding per-module options, I'm not sure special markup is needed at all. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst
I've done that now in r82961.
As per your recommendation in the updated documentation guide, I have fixed the ReST docs of stdlib modules that used :option:, to use code markup (``) instead. I've opened issue 9312 for this and submitted a patch. Eli
Le 19/07/2010 04:57, Eli Bendersky a écrit :
On Sat, Jul 17, 2010 at 16:44, Éric Araujo <merwok@netwok.org> wrote:
I think this is a doc bug in Doc/documenting/markup.rst :cmdoption: and :option: are not clearly distinguished; the latter creates references to using/cmdline, the former is what you’re looking for for documenting trace.py.
I had actually misunderstood the documentation here. Georg corrected me in http://bugs.python.org/issue9288 and made the right fix (thanks!) Kind regards
Le 19/07/2010 04:57, Eli Bendersky a écrit :
On Sat, Jul 17, 2010 at 16:44, Éric Araujo <merwok@netwok.org> wrote:
I think this is a doc bug in Doc/documenting/markup.rst :cmdoption: and :option: are not clearly distinguished; the latter creates references to using/cmdline, the former is what you’re looking for for documenting trace.py.
I had actually misunderstood the documentation here. Georg corrected me in http://bugs.python.org/issue9288 and made the right fix (thanks!) Kind regards
participants (6)
-
Alexander Belopolsky -
Eli Bendersky -
Georg Brandl -
Michael Foord -
Éric Araujo -
Éric Araujo