[Python-Dev] Markup of command-line options in Python's .rst documentation

[Georg Brandl]

Am 19.07.2010 04:28, schrieb Eli Bendersky:
> On Mon, Jul 19, 2010 at 05:57, Eli Bendersky <eliben at gmail.com
> <mailto:eliben at gmail.com>> wrote:
> 
>     On Sat, Jul 17, 2010 at 16:44, Éric Araujo <merwok at netwok.org
>     <mailto:merwok at 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.