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

Michael Foord fuzzyman at voidspace.org.uk
Sun Jul 18 11:42:51 CEST 2010

On 17/07/2010 14:44, Eli Bendersky wrote:

On Sat, Jul 17, 2010 at 16:26, Michael Foord <fuzzyman at voidspace.org.uk <mailto: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. :option: is "reserved" for Python command line options so shouldn't be used for module options. We don't have specific markup for module options, so just code markup I guess.

Michael

Eli

Python-Dev mailing list Python-Dev at 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/

-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20100718/5e0030e8/attachment.html>

More information about the Python-Dev mailing list