[docs] possible bug in Sphinx's handling of the cmdoption directive

Eli Bendersky eliben at gmail.com
Sat Nov 27 14:03:13 CET 2010

This problem came up while working in issue 9264 (
http://bugs.python.org/issue9264). Copying the report from there:


There's something weird going on with cmdoption... I've applied for
subscription to the docs mailing list, but while I'm awaiting
moderator approval, here's the brain-dump. Suppose this option

.. program:: trace

.. cmdoption:: -c, --count

   Blah blah blah

And now this reference:

This is a test long :option:`--count` and then short :option:`-c`, test.

Only the -c gets linked to ..cmdoption, not --count.
If I list --count before -c in ..cmdoption, then it's the other way
around. What makes it kinda work (link both the long and short names)

.. cmdoption:: -c

   Blah blah blah

But this isn't standard (although it doesn't look too bad). Actually,
the original listing (the short name first, then the long one) is
customary in the library docs.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20101127/c166e28a/attachment.html>

More information about the docs mailing list