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

Eli Bendersky eliben at gmail.com
Sat Jul 17 15:44:21 CEST 2010

On Sat, Jul 17, 2010 at 16:26, Michael Foord <fuzzyman at voidspace.org.uk>wrote:

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

Michael, What should it link to in case of modules, however? Is there some streamlined policy as to how module command line options should look and where they should be listed? From a cursory look on some documentation files, it's unlikely.

Perhaps the answer is not to markup module options with :option: at all, because it's reserved for Python's own command-line options. Eli -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20100717/3429bf15/attachment.html>

More information about the Python-Dev mailing list