classification
Title: Fix usage of :option: markup in stdlib ReST docs
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: docs@python, eli.bendersky, eric.araujo, ezio.melotti, georg.brandl, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2010-07-20 04:19 by eli.bendersky, last changed 2011-06-09 12:27 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
issue9312.1.patch eli.bendersky, 2010-07-20 04:20 review
issue9312.2.patch eli.bendersky, 2010-08-07 13:37
issue9312.3.patch eric.araujo, 2010-08-07 14:15
Messages (22)
msg110862 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-07-20 04:19
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)
msg110863 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-07-20 04:20
Patch
msg110869 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-20 05:43
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.
msg110908 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-07-20 15:16
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``.
msg110924 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-07-20 17:17
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
msg113173 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-08-07 13:37
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
msg113174 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-08-07 14:15
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.
msg113176 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-08-07 14:33
Eric, thanks for the catch and the fix. If there's anything else, just let me know.
msg113178 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-08-07 14:37
Nothing else to say, +1 on commit.
msg121011 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-12 02:16
I hope the patch is not outdated.  Terry, Georg, are you okay with it?
msg121012 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-12 02:28
Looks good to me.
msg121015 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-12 03:05
Ok with me also to commit and backport for next releases.
msg121022 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-12 06:03
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.
msg121024 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-12 06:16
Yes, please apply.
msg121475 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-18 16:46
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.
msg121502 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-19 06:30
É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.
msg121847 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-21 03:10
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.
msg122450 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-26 11:58
Yes, you're right; you could have linked to the correct -c option by using this form:  :option:`unittest -c`
msg122485 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-26 23:47
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.
msg124103 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-16 03:55
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.
msg137958 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-06-09 12:10
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
msg137961 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-06-09 12:27
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
History
Date User Action Args
2011-06-09 12:27:31python-devsetmessages: + msg137961
2011-06-09 12:10:57python-devsetnosy: + python-dev
messages: + msg137958
2010-12-16 03:55:20eric.araujosetstatus: open -> closed
nosy: georg.brandl, terry.reedy, ezio.melotti, eric.araujo, eli.bendersky, docs@python
messages: + msg124103
2010-11-26 23:47:17eric.araujosetmessages: + msg122485
2010-11-26 11:58:51georg.brandlsetmessages: + msg122450
2010-11-21 03:10:50eric.araujosetmessages: + msg121847
2010-11-19 06:30:21eli.benderskysetmessages: + msg121502
2010-11-18 16:46:51eric.araujosetstatus: pending -> open
resolution: accepted -> fixed
messages: + msg121475

stage: commit review -> resolved
2010-11-18 04:05:37eric.araujosetstatus: open -> pending
2010-11-18 04:05:25eric.araujosetstatus: pending -> open

messages: - msg121259
2010-11-16 03:07:14eric.araujosetstatus: open -> pending
assignee: docs@python -> eric.araujo
resolution: accepted
messages: + msg121259
2010-11-12 06:16:04georg.brandlsetmessages: + msg121024
2010-11-12 06:14:07georg.brandlsetfiles: - unnamed
2010-11-12 06:03:37eli.benderskysetfiles: + unnamed

messages: + msg121022
2010-11-12 03:05:45terry.reedysetmessages: + msg121015
2010-11-12 02:28:23ezio.melottisetmessages: + msg121012
2010-11-12 02:16:09eric.araujosetmessages: + msg121011
versions: - Python 2.6
2010-08-07 14:37:18eric.araujosetmessages: + msg113178
2010-08-07 14:33:19eli.benderskysetmessages: + msg113176
2010-08-07 14:15:46eric.araujosetfiles: + issue9312.3.patch

messages: + msg113174
2010-08-07 13:37:39eli.benderskysetfiles: + issue9312.2.patch
nosy: + georg.brandl
messages: + msg113173

2010-07-21 00:21:43ezio.melottisetnosy: + ezio.melotti
2010-07-20 17:17:46eli.benderskysetmessages: + msg110924
2010-07-20 15:16:59eric.araujosetnosy: + eric.araujo
messages: + msg110908
2010-07-20 05:43:27terry.reedysetversions: + Python 2.6, Python 3.1, Python 2.7
nosy: + terry.reedy

messages: + msg110869

stage: commit review
2010-07-20 04:20:32eli.benderskysetfiles: + issue9312.1.patch
keywords: + patch
messages: + msg110863
2010-07-20 04:19:46eli.benderskycreate