On Sat, Jul 17, 2010 at 16:26, Michael Foord <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. 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/archive%40mail-archive.com
