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

[Michael Foord]

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>