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

Eli Bendersky eliben at gmail.com
Mon Jul 19 05:28:11 CEST 2010

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>

More information about the Python-Dev mailing list