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

[Eli Bendersky]

On Sat, Jul 17, 2010 at 16:26, Michael Foord <fuzzyman at voidspace.org.uk>wrote:

>  On 17/07/2010 14:23, Eli Bendersky wrote:
>
> Hello,
>
> I'm currently working, together with Terry Reedy, on improving the
> documentation of the trace module, and I ran into a peculiar convention of
> marking command-line options which seems to be widespread.
>
> Consider the documentation of timeit, for instance:
> http://docs.python.org/dev/py3k/library/timeit.html
>
> 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.
>
> The same applies for several command-line options documented for the trace
> module (for example -m and -s). This is a result of the following markup
> (again, taking the timeit module as an example) in the relevant .rst file
> (Doc/library/timeit.rst):
>
> -h/:option:`--help`
>    print a short usage message and exit
>
> The :option: markup seems to be translated by Sphinx into a link to the
> Python executable's own command line arguments. This creates the
> aforementioned problem in other modules as well, for example unittest. Is
> there really any merit in marking command-line options for modules with
> :option:, if it's only useful for Python's own options?
>
>
> If it links to the wrong thing then the markup is incorrect (unless it is
> due to a regression in Sphinx but I think that is unlikely).
>
> Michael
>


Michael,
What *should* it link to in case of modules, however? Is there some
streamlined policy as to how module command line options should look and
where they should be listed? From a cursory look on some documentation
files, it's unlikely.

Perhaps the answer is not to markup module options with :option: at all,
because it's reserved for Python's own command-line options.
Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100717/3429bf15/attachment.html>