[issue9264] trace.py documentation is incomplete
New submission from Eli Bendersky eliben@gmail.com:
The documentation of the standard 'trace' module (Doc/library/trace.rst) is sorely lacking. Arguments are not explained, some key methods are not documented at all, and the CoverageResults class isn't documented.
Usage of these appears in the example but leaves the user confused as the only source of documentation for the example is the source code of the module.
I'm attaching a patch that fixes this issue, by providing documentation for the missing parts.
The patch was generated vs. the latest SVN trunk.
---------- assignee: docs@python components: Documentation files: tracedoc.3.patch keywords: patch messages: 110344 nosy: docs@python, eli.bendersky, tjreedy priority: normal severity: normal status: open title: trace.py documentation is incomplete type: behavior versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file18009/tracedoc.3.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
I am reviewing doc + patch against the code. Do not commit yet.
---------- assignee: docs@python -> tjreedy stage: -> patch review
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
Attaching a patch vs. the 2.6 maintenance branch for the Doc/library/trace.rst file
* Fixed some formatting issues for command line options and class references * Documented all relevant user-accessible methods * Divided command-line options logically into sub-sections and improved their explanations
I ran `make html` from the Doc/ directory and made sure the HTML looks OK
---------- Added file: http://bugs.python.org/file18137/issue9262.py26.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
To the doc person who reads this: this patch is only the first for this issue. It is being submitted now since the 2.6.6 release candidate is due in 10 days. Please leave the issue open after committing this.
I have read the diff but not the patched result (cannot make such yet), so someone else should recheck the formatted result.
Marked release blocker with agreement of Barry W., who also wants to take a look too.
---------- assignee: tjreedy -> docs@python nosy: +barry priority: normal -> release blocker stage: patch review -> commit review
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Barry A. Warsaw barry@python.org added the comment:
If the changes are to the documentation only, you've confirmed that the docs build in 2.6.6, and you get the changes in before 2.6.6rc1, then you can go ahead and commit them. I don't need to review them too closely - I trust you - but if you want me to do a detailed review before rc1, let me know and I'm happy to.
---------- resolution: -> accepted
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Changes by Alexander Belopolsky belopolsky@users.sourceforge.net:
---------- nosy: +belopolsky
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Barry A. Warsaw barry@python.org added the comment:
You have about 5 hours as of this writing to apply the doc patch for Python 2.6.6 rc1 and then it will be too late to get it into Python 2.6.6 (though I might make an exception for doc-only patches like this, for post rc1).
While I haven't built the docs, I don't have any objections to the patches. If the docs build and look right, JFDI!
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Changes by Barry A. Warsaw barry@python.org:
---------- priority: release blocker -> high
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
I'll try to meet the deadline. :-)
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
Oh, this is not assigned to me. Terry, do you need help with this?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
I cannot do commits yet, so please do it. I expected this to be picked up by a doc person.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Alexander Belopolsky belopolsky@users.sourceforge.net added the comment:
Committed in release26-maint, r83549, to beat the rc1 deadline. I'll comment on a few improvements that we can do for 3.x later.
Eli,
I needed to fix white space issues in your patch before committing. Please run make patchcheck on your changes before posting a patch.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Changes by Éric Araujo merwok@netwok.org:
---------- nosy: +docs@python -georg.brandl
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Divided command-line options logically into sub-sections and improved their explanations
Using the program/cmdoption combo may be a good idea here.
---------- nosy: +eric.araujo
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
Éric, good idea - I'll do it.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
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 description:
.. 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) is:
.. cmdoption:: -c --count
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.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
I noticed too that the second form given in a cmdoption directive cannot be linked to from an option construct. The workaround looks like this: :option:`--long <-l>`. This uses a generic Sphinx (or reST) property: When using :role:`text <thing>`, “thing” will be given as argument to the role but “text” will be displayed. It’s very useful for references for example, if you don’t want title case in the middle of your sentence of if you need to rephrase the title: “Have a look at the :ref:`detailed explanation <config-explanation>`”.
Even if it can be worked around, can you report this Sphinx bug?
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
Éric,
I sent an inquiry about this problem to the docs@python.org list. In the meantime, I will implement it with the workaround you suggest (I checked it works in this case too).
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
Attaching an updated patch for Doc/library/trace.rst in 3.2
Changed the formatting of command-line options per Éric's suggestion of using program/cmdoption/option combos (great idea Éric - it looks much better).
---------- Added file: http://bugs.python.org/file19837/issue9264.py32.2.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Thanks for your work on this!
``dir/package/module.cover`` → :file:`{dir}/{package}/{module}.cover`
'``>>>>>>``' looks wrong.
``os.pathsep``: You can use :data:`os.pathsep` to get a link, I think.
+.. method:: CoverageResults.update(other) FTR, there is a new way for doing such things: You can nest method directives in a class directive block. See gettext.rst for an example. Your patch needn’t change that now, not all docs have been updated, so it’s best to do as you did and follow the style of the rest of the file. I propose to change it after your patch is committed.
+.. Stray dots at the end of the file.
The doc uses one or two spaces inconsistently. I don’t know if it’s worth changing.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
Attaching an updated patch following Éric's suggestions:
* ``dir/package/module.cover`` -- FIXED
* '``>>>>>>``' looks wrong -- FIXED to just ``>>>>>>``
* ``os.pathsep`` -- FIXED
* method:: CoverageResults.update(other) -- OK, let's leave it for a separate issue.
* Stray dots at the end of the file -- FIXED
* The doc uses one or two spaces inconsistently. -- not 100% what you mean here, but I found inconsistent separation between paragraphs (sometimes 1 blank line, sometimes 2), and fixed it. If you meant something else, I can fix that too :)
---------- Added file: http://bugs.python.org/file19838/issue9264.py32.3.patch
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Duh, I forgot some words: The file uses one or two dots *after full stops* inconsistently. I don’t think you have to change that now, we can make it consistent later (or not, as it does not affect the output), as we do with line wrapping. Just keep it in mind for future patches :)
Terry: I got no warnings when building the HTML and the output looks good. +1 on commit.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
Éric, please feel free to commit (and even grab Assigned To:) when you feel patch is ready. You can do final review better than me.
---------- versions: -Python 3.1
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Changes by Éric Araujo merwok@netwok.org:
---------- assignee: terry.reedy -> eric.araujo status: open -> pending versions: +Python 3.1
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
Guys, this issue is pending for a long time. Anything else needed before a commit is done?
---------- status: pending -> open
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Changes by Eli Bendersky eliben@gmail.com:
---------- status: open -> pending
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
Since Éric grabbed Assigned To:, I was expecting him to ;=). But since he is doing enough other stuff, I will unless there are conflicts in the .rst I do not know how to fix.
---------- status: pending -> open
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
My current schedule is a bit crazy and I’ve had no time for Python bugs.
I changed “programming” to “programmatic”, slightly tweaked the phrasing for the --ignore-* options to make them hopefully more understandable and similar, and committed in r87271.
I’m currently rewrapping long lines and migrating the class/method constructs to be nested. I will then backport the parts of both commits that apply to 3.1 and 2.7.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Terry J. Reedy tjreedy@udel.edu added the comment:
Éric beat me. Better that he finish.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Minor whitespace and markup edits make r87273. Please review and tell me if it’s okay for backport or if there are further improvements to be done first. I promise I won’t beat anyone ;-)
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Eli Bendersky eliben@gmail.com added the comment:
Éric,
The nested methods are nice, though a bit unusual IMHO. Is this the recommended new way to markup methods of objects? [Because AFAIK it's not used much in other docs]
---------- status: open -> pending
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
The nesting allows logical grouping in source and output, saves a bit of typing, and has been added to a number of files by Benjamin Peterson. I’d say it’s recommended :)
---------- status: pending -> open
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Georg Brandl georg@python.org added the comment:
Yes, it's the new recommended style. (Please add to documenting/ when convenient :)
---------- nosy: +georg.brandl
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Changes by Éric Araujo merwok@netwok.org:
---------- status: open -> pending
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Backported in r88324 and r88328.
---------- resolution: accepted -> fixed stage: patch review -> committed/rejected status: pending -> closed
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
Éric Araujo merwok@netwok.org added the comment:
Nesting of class/method and class/data directives recommended in 584f9c213a6d.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue9264 _______________________________________
participants (6)
-
Alexander Belopolsky -
Barry A. Warsaw
-
Eli Bendersky
-
Georg Brandl
-
Terry J. Reedy
-
Éric Araujo