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