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

[Eli Bendersky]

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?

Eli
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100717/09df572a/attachment.html>