[issue9312] Fix usage of :option: markup in stdlib ReST docs
New submission from Eli Bendersky <eliben@gmail.com>: 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) ---------- assignee: docs@python components: Documentation messages: 110862 nosy: docs@python, eli.bendersky priority: normal severity: normal status: open title: Fix usage of :option: markup in stdlib ReST docs type: behavior versions: Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Patch ---------- keywords: +patch Added file: http://bugs.python.org/file18080/issue9312.1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- nosy: +tjreedy stage: -> commit review versions: +Python 2.6, Python 2.7, Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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``. ---------- nosy: +merwok _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: 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 ---------- nosy: +georg.brandl Added file: http://bugs.python.org/file18424/issue9312.2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- Added file: http://bugs.python.org/file18425/issue9312.3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Eric, thanks for the catch and the fix. If there's anything else, just let me know. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Nothing else to say, +1 on commit. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I hope the patch is not outdated. Terry, Georg, are you okay with it? ---------- versions: -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Looks good to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: Ok with me also to commit and backport for next releases. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: 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. ---------- Added file: http://bugs.python.org/file19577/unnamed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Georg Brandl <georg@python.org>: Removed file: http://bugs.python.org/file19577/unnamed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Georg Brandl <georg@python.org> added the comment: Yes, please apply. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Can I commit doc patches like this one despite the branch freeze? ---------- assignee: docs@python -> eric.araujo resolution: -> accepted status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- status: pending -> open Removed message: http://bugs.python.org/msg121259 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@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@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: É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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Georg Brandl <georg@python.org> added the comment: Yes, you're right; you could have linked to the correct -c option by using this form: :option:`unittest -c` ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Roundup Robot <devnull@devnull> added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Roundup Robot <devnull@devnull> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Patch ---------- keywords: +patch Added file: http://bugs.python.org/file18080/issue9312.1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- nosy: +tjreedy stage: -> commit review versions: +Python 2.6, Python 2.7, Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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``. ---------- nosy: +merwok _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: 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 ---------- nosy: +georg.brandl Added file: http://bugs.python.org/file18424/issue9312.2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- Added file: http://bugs.python.org/file18425/issue9312.3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Eric, thanks for the catch and the fix. If there's anything else, just let me know. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Nothing else to say, +1 on commit. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I hope the patch is not outdated. Terry, Georg, are you okay with it? ---------- versions: -Python 2.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Looks good to me. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: Ok with me also to commit and backport for next releases. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: 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. ---------- Added file: http://bugs.python.org/file19577/unnamed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Georg Brandl <georg@python.org>: Removed file: http://bugs.python.org/file19577/unnamed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Georg Brandl <georg@python.org> added the comment: Yes, please apply. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Can I commit doc patches like this one despite the branch freeze? ---------- assignee: docs@python -> eric.araujo resolution: -> accepted status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- status: pending -> open Removed message: http://bugs.python.org/msg121259 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@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@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: É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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Georg Brandl <georg@python.org> added the comment: Yes, you're right; you could have linked to the correct -c option by using this form: :option:`unittest -c` ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: 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. ---------- status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Roundup Robot <devnull@devnull> added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
Roundup Robot <devnull@devnull> added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue9312> _______________________________________
participants (6)
-
Eli Bendersky -
Ezio Melotti
-
Georg Brandl
-
Roundup Robot
-
Terry J. Reedy
-
Éric Araujo