homepage

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.

I am reviewing doc + patch against the code. Do not commit yet.

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

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.

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.

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!

I'll try to meet the deadline. :-)

Oh, this is not assigned to me. Terry, do you need help with this?

I cannot do commits yet, so please do it. I expected this to be picked up by a doc person.

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.

I think it makes sense to commit the same patch to 2.7, is this planned?

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?

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.

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

> 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.

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.

> Divided command-line options logically into sub-sections and improved
> their explanations
Using the program/cmdoption combo may be a good idea here.

Éric, good idea - I'll do it.

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.

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?

É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).

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).

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.

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 :)

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.

É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.

Guys, this issue is pending for a long time. Anything else needed before a commit is done?

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.

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.

Éric beat me. Better that he finish.

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 ;-)

É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]

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 :)

Yes, it's the new recommended style. (Please add to documenting/ when convenient :)

Backported in r88324 and r88328.

Nesting of class/method and class/data directives recommended in 584f9c213a6d.