Due to a discussion on python-dev (Subject: "Markup of command-line options in Python's .rst documentation"), Georg Brandl checked in revision r82961 with a clarification of :option: markup which should only be used for Python interpreter's own flags.

However, several modules in stdlib use :option: for their own command-line options, which creates confusion (these options get linked by Sphinx to unrelated Python options).

I'm attaching a patch that fixes this issue for these files. The affected files are:

Doc/library/idle.rst
Doc/library/timeit.rst
Doc/library/test.rst
Doc/library/doctest.rst
Doc/library/unittest.rst
Doc/library/pydoc.rst
Doc/library/webbrowser.rst
Doc/library/compileall.rst

Note1: :option: was fixed to `` markup (code snippet) as per the recommendation in the updated documentation guide
Note2: I didn't patch trace.rst because it's overgoing a major rehaul (http://bugs.python.org/issue9264)

Patch

The patch generally changes things like 

:option:`-e`   to   ``-e``   and

-r N/:option:`--repeat=N`   to   ``-r N/--repeat=N``

which is what I understand GB to have said to do.

:program:`python regrtest.py` :option:`test_spam.py`  to
:program:`python regrtest.py test_spam.py`

For the last, I presume that :program:`...` takes the place of ``...``
in the previous examples.

There are a few text changes in doctest.rst that I cannot comment on.

I presume this could and should be backported from 3.2 to other versions. Eli said in email that he has run 'make html' and checked the output.

In documenting/markup:

program
    The name of an executable program. This may differ from the file name for the executable for some platforms. In particular, the .exe (or other) extension should be omitted for Windows programs.

So I believe the correct form would be ``python regrtest.py``.

Terry, 
Re doctest.rst - appears to be a merging issue. I will see how to resolve it once we figure out what to do with :program:

Éric, 
Good point - I'll ask pydev and will update the patch accordingly

Following the discussions on pydev and some private correspondence with Georg Brandl, I'm attaching an updated patch.

Things changed:

1. Changes of :option: to ``...`` similar to previous patch

2. :program:`prog` :option:`opt` was changed to ``prog opt``

3. Some modules have a large choice of command line options. Per Georg's suggestions, command line options in these modules can be described with the "cmdoption" directive and later referred to with :option: which inserts a back-link, just like to the Python interpreter options now. I've applied these changes to unittest.rst and timeit.rst. trace.rst also has this problem, but the trace documentation is currently undergoing a major change by issue 9264 (2.6 fix was already committed) and I prefer changing it wholly at once.

In addition, the documentation of optparse underwent a more serious change because it kept referring to options with ``"-o"`` (note the double quotes after the ``), I changed it to ``-o`` for consistency.

--------

P.S. The patch was generated from a fresh pull of py3k from the Hg mirror. The complete list of affected files:

M Doc/library/codecs.rst
M Doc/library/compileall.rst
M Doc/library/doctest.rst
M Doc/library/exceptions.rst
M Doc/library/getopt.rst
M Doc/library/idle.rst
M Doc/library/optparse.rst
M Doc/library/pydoc.rst
M Doc/library/sys.rst
M Doc/library/test.rst
M Doc/library/timeit.rst
M Doc/library/unittest.rst
M Doc/library/webbrowser.rst

Nice changes! Especially the program/cmdoption directives combo.

Your patch introduces trailing whitespace (good editor settings can show those, as well as hg diff with the color extension) and has one unnecessary change:

-line, ``options.filename`` will be ``"outfile"`` and ``options.verbose`` will be
+line, ``options.filename`` will be ``outfile`` and ``options.verbose`` will be

In this case, the things in ```` are not command line snippets but Python code, so the quotes are regular string notation.

Attached patch fixes that.

Eric, thanks for the catch and the fix. If there's anything else, just let me know.

Nothing else to say, +1 on commit.

I hope the patch is not outdated.  Terry, Georg, are you okay with it?

Looks good to me.

Ok with me also to commit and backport for next releases.

On Fri, Nov 12, 2010 at 05:05, Terry J. Reedy <report@bugs.python.org>wrote:

Please let me know if there are problems applying it and with which
versions, I will fix it up to bring it up to date. It's a tricky patch
(affects many files in many places), so there might be difficulties.

Yes, please apply.

Patch tweaked and committed in r86521.  Gory details follow.

The patch applied with only two fuzzy hunks and one rejected hunk.

I did a careful review of "" → ``""`` changes and edited a number of them.  I’m confident in my choices but am of course open to comments on the checkin.

My remark about not using :program:`name --option` was wrong.  It is actually supported, see for instance in shutil.rst “Unix command :program:`cp -p`”.  I apologize for causing you unnecessary work.  I changed that back before committing.

I ran “make clean html” in the docs (no warnings) and looked at the HTML output for each change.  Modules that wrongly used :option: are fixed; conversely, timeit and unittest now have a good-looking, indexed list of options, the program/cmdoption combo you used is terrific!

Actually, I found that so cool that I added an option list for “unittest discover” (was a table) and “compileall” (was a plain paragraph, missing two options).  Consider that an experiment; I’m willing to revert them if people prefer the old form.

I’ll rewrap too long or too short lines in a following commit.  I’ll also backport relevant parts to 3.1 and 2.7 with the approval of the release manager.

Thank you Eli for this contribution.  Thanks Terry and Georg for the help.

Éric,

I went over both the diffs and the HTML output from "make clean html" on the latest 3.2 trunk. Looks good to me!

Just a tiny nit re unittest.rst, where it says "supports three command-line options". This is the kind of comment that gets left behind when new options are added. I see no added value explicitly saying there are 3 options as opposed to "supports the following command-line options", and there's less chance for future mistakes. It's also more consistent with the list of options for "discover" a bit later in the same document. This is totally a stylistic issue, of course, so IMVHO :-)

Oh, and another thing about unittest.rst: in 24.3.9 where it says "The -c command-line option to unittest", for some reason the -c didn't get linked to the option, although I think you intended it to, since you marked it as :option:

P.S: the program/cmdoption combo idea was Georg's.

Thanks for the review.  I agree and committed changes in r86632.

The problem with :option:`-c` is probably that Sphinx wants to find a “.. cmdoption:: -c” joined with the latest program directive it has seen, and thus can’t find the -c defined with a previous program directive.  I fought hard with that, trying :option:`-c <cmdoption-unittest-c>` and :ref:, but no luck.  I finally just used ```` markup.  When #10470 is implemented the two option lists will be merged and I’ll be able to use :option:`-c`.

Georg, it would be nice if you could confirm or infirm my analysis.

Yes, you're right; you could have linked to the correct -c option by using this form:  :option:`unittest -c`

Great, thanks!  New markup committed as r86823, long lines rewrapped in r86824 (along with a few minor touch-ups).

I think we’re good now, I’ll backport shortly.

I removed one instance of unnecessary markup in r87294 (pointed by Michael Foord on IRC) and made other minor changes in r87296, r87300 and r87302.

Those eight commits are now merged in 3.1 as r87305 and 2.7 as r87308.  Please let me know if you find any merge glitches.  Happily closing.

New changeset 59d785ea0039 by Éric Araujo in branch '3.2':
Fix a few misuses of :option: I missed in r86521.
http://hg.python.org/cpython/rev/59d785ea0039

New changeset 7164bdfa0b0b by Éric Araujo in branch '2.7':
Fix a few misuses of :option: I missed in r86521.
http://hg.python.org/cpython/rev/7164bdfa0b0b