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

Eli

_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/fuzzyman%40voidspace.org.uk


-- 
http://www.ironpythoninaction.com/
http://www.voidspace.org.uk/blog

READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.