[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@netwok.org added the comment: Nesting of class/method and class/data directives recommended in 584f9c213a6d. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@netwok.org added the comment: Backported in r88324 and r88328. -- resolution: accepted - fixed stage: patch review - committed/rejected status: pending - closed ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Changes by Éric Araujo mer...@netwok.org: -- status: open - pending ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Georg Brandl ge...@python.org added the comment: Yes, it's the new recommended style. (Please add to documenting/ when convenient :) -- nosy: +georg.brandl ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Changes by Eli Bendersky eli...@gmail.com: -- status: open - pending ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Terry J. Reedy tjre...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Terry J. Reedy tjre...@udel.edu added the comment: Éric beat me. Better that he finish. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@gmail.com added the comment: Éric, good idea - I'll do it. -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@gmail.com added the comment: Éric, I sent an inquiry about this problem to the d...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@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 rep...@bugs.python.org
http://bugs.python.org/issue9264
___
___
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Terry J. Reedy tjre...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Changes by Éric Araujo mer...@netwok.org: -- assignee: terry.reedy - eric.araujo status: open - pending versions: +Python 3.1 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Éric Araujo mer...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Changes by Éric Araujo mer...@netwok.org: -- nosy: +d...@python -georg.brandl ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@gmail.com added the comment: 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. -- Added file: http://bugs.python.org/file19578/issue9264.py32.1.patch ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: 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. -- priority: high - normal ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@gmail.com added the comment: 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 -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@gmail.com added the comment: I think it makes sense to commit the same patch to 2.7, is this planned? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Terry J. Reedy tjre...@udel.edu added the comment: 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? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: 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. -- nosy: +georg.brandl ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Barry A. Warsaw ba...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Changes by Barry A. Warsaw ba...@python.org: -- priority: release blocker - high ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: I'll try to meet the deadline. :-) -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Alexander Belopolsky belopol...@users.sourceforge.net added the comment: Oh, this is not assigned to me. Terry, do you need help with this? -- ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Terry J. Reedy tjre...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Alexander Belopolsky belopol...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Changes by Terry J. Reedy tjre...@udel.edu: -- assignee: d...@python - tjreedy nosy: -barry, d...@python stage: commit review - patch review versions: -Python 2.6 ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Changes by Alexander Belopolsky belopol...@users.sourceforge.net: -- nosy: +belopolsky ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Eli Bendersky eli...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Terry J. Reedy tjre...@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 - d...@python nosy: +barry priority: normal - release blocker stage: patch review - commit review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Barry A. Warsaw ba...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
Terry J. Reedy tjre...@udel.edu added the comment: I am reviewing doc + patch against the code. Do not commit yet. -- assignee: d...@python - tjreedy stage: - patch review ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue9264] trace.py documentation is incomplete
New submission from Eli Bendersky eli...@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: d...@python components: Documentation files: tracedoc.3.patch keywords: patch messages: 110344 nosy: d...@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 rep...@bugs.python.org http://bugs.python.org/issue9264 ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
