[issue14945] Setup & Usage documentation for selected stdlib modules
New submission from Nick Coghlan <ncoghlan@gmail.com>: Some stdlib modules have officially documented and supported behaviour when executed via -m. These should be referenced from the Setup & Usage documentation at http://docs.python.org/dev/using/index.html Current candidates: python -m unittest python -m timeit ---------- assignee: docs@python components: Documentation messages: 161832 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for selected stdlib modules type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: I'm sure there's a predecessor to this issue that I intend for this one to replace, but I can't currently find it in order to mark it as superceded. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Found it: #11260. I've left it open, since the original suggestion in that issue is related to actually documenting the -m behaviour of the smptd module - it was just the issue *discussion* that ended up covering the more general question of how such command line interfaces should be documented. The current issue is specifically about providing a central index in the setup and usage documentation to those modules which *already* have officially documented and supported behaviour when executed with -m. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: Additional candidates after grepping the docs: python -m site python -m sysconfig python -m pickle python -m pickletools python -m compileall python -m test ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I’d propose to add one file per script / module-as-script, except maybe for -m site and -m sysconfig which are more about debugging an installation than really using a feature provided by the stdlib. ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Nick Coghlan <ncoghlan@gmail.com> added the comment: I think for these it's reasonable to just have an index page that references out to the individual module docs. Most of them are closely related to using the module in your own code and/or there's general background info in the module docs that you're likely to need in order to understand what the tool is for. The main thing I'm after at this point is for Setup & Usage to act as a central index for using Python from the command line, rather than it necessarily containing all the details directly. Rather than trying too hard to categorise them, I'd be inclined to start with a simple alphabetical list (module name linking to the relevant section in the module docs, adding it if it doesn't already exist). Something like: compileall - Precompiling Python source modules to bytecode pickle - Display the contents of pickles saved as files pickletools - Analyse the contents of pickles saved as files site - Display details of Python's configuration sysconfig - Display additional details of Python's configuration test - Execute Python's own regression test suite timeit - Microbenchmarking for small Python snippets unittest - Find and execute unit tests Maybe we'll decide to do something more long term, but I think this is a good way to start. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Changes by A.M. Kuchling <lists@amk.ca>: ---------- nosy: +akuchling _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti versions: +Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Mark Lawrence added the comment: Where do we stand with this and #11260 ? ---------- nosy: +BreamoreBoy versions: +Python 3.5 -Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Changes by A.M. Kuchling <amk@amk.ca>: ---------- nosy: -akuchling _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________
Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue14945> _______________________________________
participants (6)
-
A.M. Kuchling -
Ezio Melotti
-
Mark Lawrence
-
Nick Coghlan
-
Tshepang Lekhonkhobe
-
Éric Araujo