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

[Eli Bendersky]

On Mon, Jul 19, 2010 at 05:57, Eli Bendersky <eliben at gmail.com> wrote:

> On Sat, Jul 17, 2010 at 16:44, Éric Araujo <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

Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100719/5aed0079/attachment.html>