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

[Eli Bendersky]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100719/a4fb7934/attachment.html>