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

[Michael Foord]

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 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/
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.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20100717/89cfaf06/attachment.html>