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