<div dir="ltr">Hello,<br><br>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. <br>
<br>Consider the documentation of timeit, for instance: <a href="http://docs.python.org/dev/py3k/library/timeit.html">http://docs.python.org/dev/py3k/library/timeit.html</a><br><br>The "--help" option appears as a hyperlink leading to <a href="http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help">http://docs.python.org/dev/py3k/using/cmdline.html#cmdoption--help</a>, which is hardly relevant or useful. <br>
<br>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):<br>
<br>-h/:option:`--help`<br> print a short usage message and exit<br><br>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?<br>
<br>Eli<br><br></div>