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>
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4