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