On Mon, Jul 19, 2010 at 05:57, Eli Bendersky <eli...@gmail.com> wrote:
> On Sat, Jul 17, 2010 at 16:44, Éric Araujo <mer...@netwok.org> wrote: > >> > 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. [...] >> > >> > -h/:option:`--help` >> > print a short usage message and exit >> >> I think this is a doc bug in Doc/documenting/markup.rst >> :cmdoption: and :option: are not clearly distinguished; the latter >> creates references to using/cmdline, the former is what you’re looking >> for for documenting trace.py. >> > > How would you guys recommend to proceed from here? > > The simplest approach for me is just use :cmdoption: instead of :option: in > my work on trace.py . However, a few more things can be done if this is > indeed "official policy": > > 1. Fix other modules that use :option: to use :cmdoption: instead (timeit, > unittest and others) > 2. Fix Doc/documenting/markup.rst to clarify which option kind goes where > > If these steps get approved I'll be happy to create an issue and submit > patches to the relevant files. > > Eli > More input on this issue: 'cmdoption' is a directive, while 'option' is inline markup. Therefore I wouldn't say they're completely similar, just meant for different purposes. Both a directive and inline markup is useful for describing "official python executable options/flags". Regarding per-module options, I'm not sure special markup is needed at all. So a policy has to be define regarding the correct usage of these directives/markups, and probably documented in Doc/documenting/markup.rst 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