[docs] [issue9312] Fix usage of :option: markup in stdlib ReST docs

[Éric Araujo]

Éric Araujo <merwok at netwok.org> added the comment:

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.

----------
resolution: accepted -> fixed
stage: commit review -> committed/rejected
status: pending -> open

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue9312>
_______________________________________