classification
Title: trace.py documentation is incomplete
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: belopolsky, docs@python, eli.bendersky, eric.araujo, georg.brandl, terry.reedy
Priority: normal Keywords: patch

Created on 2010-07-15 04:11 by eli.bendersky, last changed 2011-04-27 14:51 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
tracedoc.3.patch eli.bendersky, 2010-07-15 04:11 review
issue9262.py26.patch eli.bendersky, 2010-07-23 08:18 review
issue9264.py32.1.patch eli.bendersky, 2010-11-12 10:03
issue9264.py32.2.patch eli.bendersky, 2010-11-27 14:25
issue9264.py32.3.patch eli.bendersky, 2010-11-27 15:17
Messages (36)
msg110344 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-07-15 04:11
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.
msg110374 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-15 15:41
I am reviewing doc + patch against the code. Do not commit yet.
msg111252 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-07-23 08:18
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
msg111363 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-07-23 16:49
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.
msg111393 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2010-07-23 21:54
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.
msg112489 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2010-08-02 16:12
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!
msg112492 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-08-02 16:22
I'll try to meet the deadline. :-)
msg112493 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-08-02 16:23
Oh, this is not assigned to me.  Terry, do you need help with this?
msg112512 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-02 18:52
I cannot do commits yet, so please do it. I expected this to be picked up by a doc person.
msg112522 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-08-02 19:33
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.
msg113083 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-08-06 07:31
I think it makes sense to commit the same patch to 2.7, is this planned?
msg113110 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-08-06 16:46
Fine with me.
Alexander, do you have the fixed up version you committed to 2.6, or should Eli revise the attachment here for 2.7?
msg113119 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-08-06 17:39
The fixed up version is just r83549. It may merge cleanly with py3k - I believe doc changes are trivial if any between 2.6 and 3.x.

I would like this to go through another round of reviews without release calendar pressure.  I would like to see some guidelines for documenting command line options to stdlib modules.  In this particular patch, I don't like "Meta-options" sections.  No other module document has such section.  The --help and --version are not "meta-options", they are "common options". I would also like to see a mention that  one of --trace, --count, --report, --listfuncs, or --trackcalls must be specified.  (Even better would be to make one of these options the default behavior when no options are given.  Required option is an oxymoron.)

Terry,

This is in your hands now.  If you prefer to merge the change and postpone the improvements, it is fine with me.
msg113747 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-08-13 07:27
Alexander, I agree that the documentation isn't yet in a perfect state and can be further improved. Since there's still time for the next milestone of 3.2, there's no reason not to improve it.

So I'm open to ideas and am willing to submit improved patches for 3.2
msg116558 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-09-16 15:06
> So I'm open to ideas and am willing to submit improved patches for 3.2

I offered some ideas in my last message.  In addition, I would like to see profile and trace documentation to converge to similar structure and use similar terminology.  In particular, I don't like "Run *cmd* under control of the Trace object" because Trace is not a debugger and does not "control" the execution.  I think the explanation at http://docs.python.org/dev/py3k/library/profile.html#cProfile.run is better.  On the other hand, I like "Programming Interface" as the title of the API section better than "Reference Manual" in profile docs.  I hope we can change both trace and profile sections and retain the best choices.
msg121031 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-12 10:03
Alexander,

I'm submitting a patch for Doc/library/trace.rst for 3.2, incorporating the stylistic changes you propose.

It would be really great to see this fixed for the next release of 3.2, since the documentation improvement is major, and it's already in for 2.6

Perhaps if this is found acceptable, the same patch could be applied to 2.7 as well.

Let me know if any more fixes are needed, I will make my best attempt to respond promptly.
msg122491 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-27 00:31
> Divided command-line options logically into sub-sections and improved
> their explanations

Using the program/cmdoption combo may be a good idea here.
msg122509 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-27 08:37
Éric, good idea - I'll do it.
msg122510 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-27 08:52
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.
msg122521 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-27 12:38
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?
msg122523 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-27 13:20
É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).
msg122526 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-27 14:25
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).
msg122529 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-27 15:07
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.
msg122531 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-11-27 15:17
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 :)
msg122532 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-27 16:01
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.
msg122558 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-27 21:04
É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.
msg124039 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-12-15 18:40
Guys, this issue is pending for a long time. Anything else needed before a commit is done?
msg124048 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-12-15 19:13
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.
msg124050 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-15 19:16
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.
msg124051 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-12-15 19:27
Éric beat me. Better that he finish.
msg124052 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-15 19:32
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 ;-)
msg124058 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2010-12-15 19:48
É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]
msg124079 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-15 22:29
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 :)
msg124221 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-12-17 15:59
Yes, it's the new recommended style.  (Please add to documenting/ when convenient :)
msg127778 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-02-03 00:13
Backported in r88324 and r88328.
msg134572 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-04-27 14:51
Nesting of class/method and class/data directives recommended in 584f9c213a6d.
History
Date User Action Args
2011-04-27 14:51:35eric.araujosetmessages: + msg134572
2011-02-03 00:13:38eric.araujosetstatus: pending -> closed
nosy: georg.brandl, terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg127778

resolution: accepted -> fixed
stage: patch review -> resolved
2011-01-08 23:15:33eric.araujosetstatus: open -> pending
nosy: georg.brandl, terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
2010-12-17 15:59:34georg.brandlsetnosy: + georg.brandl
messages: + msg124221
2010-12-15 22:29:03eric.araujosetstatus: pending -> open
nosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg124079
2010-12-15 19:48:36eli.benderskysetstatus: open -> pending
nosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg124058
2010-12-15 19:32:19eric.araujosetnosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg124052
2010-12-15 19:27:51terry.reedysetnosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg124051
2010-12-15 19:16:05eric.araujosetnosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg124050
2010-12-15 19:13:38terry.reedysetstatus: pending -> open
nosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg124048
2010-12-15 18:43:47eli.benderskysetstatus: open -> pending
nosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
2010-12-15 18:40:52eli.benderskysetstatus: pending -> open
nosy: terry.reedy, belopolsky, eric.araujo, eli.bendersky, docs@python
messages: + msg124039
2010-11-28 05:43:47eric.araujosetstatus: open -> pending
assignee: terry.reedy -> eric.araujo
versions: + Python 3.1
2010-11-27 21:04:54terry.reedysetmessages: + msg122558
versions: - Python 3.1
2010-11-27 16:01:06eric.araujosetmessages: + msg122532
2010-11-27 15:17:31eli.benderskysetfiles: + issue9264.py32.3.patch

messages: + msg122531
2010-11-27 15:07:38eric.araujosetmessages: + msg122529
2010-11-27 14:25:33eli.benderskysetfiles: + issue9264.py32.2.patch

messages: + msg122526
2010-11-27 13:20:19eli.benderskysetmessages: + msg122523
2010-11-27 12:38:00eric.araujosetmessages: + msg122521
2010-11-27 08:52:45eli.benderskysetmessages: + msg122510
2010-11-27 08:37:22eli.benderskysetmessages: + msg122509
2010-11-27 00:31:43eric.araujosetnosy: + eric.araujo
messages: + msg122491
2010-11-22 06:27:46eric.araujosetnosy: + docs@python, - georg.brandl
2010-11-12 10:03:35eli.benderskysetfiles: + issue9264.py32.1.patch

messages: + msg121031
2010-09-16 15:06:44belopolskysetpriority: high -> normal

messages: + msg116558
2010-08-13 07:27:29eli.benderskysetmessages: + msg113747
2010-08-06 17:39:23belopolskysetnosy: + georg.brandl
messages: + msg113119
2010-08-06 16:46:23terry.reedysetmessages: + msg113110
2010-08-06 07:31:33eli.benderskysetmessages: + msg113083
2010-08-02 20:07:55terry.reedysetassignee: docs@python -> terry.reedy
stage: commit review -> patch review

nosy: - barry, docs@python
versions: - Python 2.6
2010-08-02 19:33:07belopolskysetmessages: + msg112522
2010-08-02 18:52:03terry.reedysetmessages: + msg112512
2010-08-02 16:23:50belopolskysetmessages: + msg112493
2010-08-02 16:22:10belopolskysetmessages: + msg112492
2010-08-02 16:12:37barrysetpriority: release blocker -> high
2010-08-02 16:12:15barrysetmessages: + msg112489
2010-07-30 16:49:23belopolskysetnosy: + belopolsky
2010-07-23 21:54:19barrysetresolution: accepted
messages: + msg111393
2010-07-23 16:49:37terry.reedysetpriority: normal -> release blocker

nosy: + barry
messages: + msg111363

assignee: terry.reedy -> docs@python
stage: patch review -> commit review
2010-07-23 08:18:58eli.benderskysetfiles: + issue9262.py26.patch

messages: + msg111252
2010-07-15 15:41:41terry.reedysetassignee: docs@python -> terry.reedy
messages: + msg110374
stage: patch review
2010-07-15 04:11:24eli.benderskycreate