On 17/07/2010 14:44, Eli Bendersky wrote:
On Sat, Jul 17, 2010 at 16:26, Michael Foord
<fuzzy...@voidspace.org.uk <mailto:fuzzy...@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@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/
_______________________________________________
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/archive%40mail-archive.com
