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?