[issue28972] Document all "python -m" utilities

[Aaron Hall]

Aaron Hall added the comment:

I like this idea too, but perhaps it should just be a multi-column bulleted 
list (under the -m flag at 
https://docs.python.org/3/using/cmdline.html#interface-options) with links to 
the respective Standard Library doc?

Then we just ensure the documentation for the module is complete with examples 
for the command line usage.

--
nosy: +Aaron Hall

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Steve Barnes]

Steve Barnes added the comment:

Having done some checks for the practicality of auto documenting library items 
with a -m command line usage I have to say that it will not be so simple. 

Many of the library items that provide useful functionality, including zipfile 
& tarfile, are implemented as single .py files, rather than as modules so have 
no __main__.py to trigger the inclusion in auto-generated documentation. 

I also tried searching for standard library items that use `if __name__ == 
"__main__":` constructs but, of course, many files simply use that to expose 
tests rather than useful functionality - so that is out as well. I even thought 
of trying for a regex that would look for this followed, in the same scope by 
argparse but of course there is no obligation to use it.

And of course main() does not HAVE to be called main so that is out.

Sorry to scotch the idea Eric!

--
nosy: +Steve Barnes

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Eric Lafontaine]

Eric Lafontaine added the comment:

Hi,

I've just watched the old David Beazley video about the packaging system in 
python and got me thinking about this issue.

I'm throwing the idea, please critize it!

If we were to make a "hook" for the .rst files of the modules to go and scan 
the __main__.py file for the comments, generating the 'index' of all those 
options from the comments inside the file (__main__.py).  That would be in my 
opinion a solution to make sure they are kept to date and would also insure 
someone knows minimally what he's doing as he's playing inside the main of a 
package.  The idea is similar to the autodoc module of sphinx that scan a 
module for the doc, but would apply to the __main__.py only.  However, I've 
just started with .rst files and I'm not sure how we could 'implement' that and 
even less if it's possible at all.

(BTW, I would only enable the .rst "hook" option generation on the __main__.py 
file as to keep sort of a standardisation but not obligation)

P.S. I know I initially seems skeptical, but I have started to see the use 
thanks to you :)  The example was good (msg283470).  
Regards,
Eric Lafontaine

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Miki Tebeka]

Miki Tebeka added the comment:

Thanks Guido, however I think my blog is not the right place - it's dog ugly 
and read by about 7 people on a good day :) 

I think that adding this to the official docs will add to the "batteries 
included" motto. I'll try to find a time and come up with a patch to the docs, 
however if this goes through we should place a note somewhere in the 
development docs about updating this section as well if someone adds a 
__main__.py or main function.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Guido van Rossum]

Guido van Rossum added the comment:

I'm neutral on this idea.  I would much rather focus on making sure that the 
various modules (such as pdb or tarfile) which have useful command-line 
functionality document that clearly and uniformly, but as part of each module's 
library docs.

I don't think that a list of all modules that have such behavior really belongs 
in the stdlib docs, but if someone wants to add it and keep it up to date I 
won't object.  Just understand that whatever is documented must preserve some 
sort of backwards compatibility.  And don't repeat the same information in two 
places.

Maybe the blog post that started this is actually enough?  Or if something more 
official is needed, perhaps a how-to document?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Miki Tebeka]

Miki Tebeka added the comment:

Eric - sorry I wasn't clear. I'm not talking about the -m behavior in general 
but on the modules in the standard library that can be used with it. A lot of 
windows are happy to know about "python -m tarfile" to they can extract tar 
files without installing an extra tool and some Linux people are happy to know 
on "python -m zipfile" so they don't have to install the "zip" utility to 
extract/create zip archives. etc ...

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Raymond Hettinger]

Raymond Hettinger added the comment:

+1 for Miki's idea.  It would be nice if there were a single page that 
collected together all the command-line tools (with examples).  It should 
include a 2to3 example as well.  Also, there should be some indication of which 
tools we guarantee to be available (2to3 json.tool) versus those that just 
happen to be exposed but are subject to change (possibly because they were just 
used for testing, or because they have a crummy API, or because Guido has said 
that we are in the library business, not the command-line tool business).

See also:  http://bugs.python.org/issue26488

--
assignee: docs@python -> 
nosy: +gvanrossum, rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Eric Lafontaine]

Eric Lafontaine added the comment:

Hi,

I believe it's already done.  The only thing that people tends to forget is 
that doing python -m "module.script(.py)" is only doing the equivalent of 
"python module/script.py". 

I believe it's clear though ;
https://docs.python.org/3/using/cmdline.html#cmdoption-m

Any module that anyone has done can do it, so it would be up to the module 
developer to put it in the README/Description of the module to describe how to 
use it.  That's what I think

BTW, I'm just giving my opinion out of contributing.  Please don't see it as a 
denial as it's not the case.  Python strive to be clearer but has 20 years of 
existence.  Enhancing it is hard.

Regards,
Eric Lafontaine

--
nosy: +Eric Lafontaine

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue28972] Document all "python -m" utilities

[Miki Tebeka]

New submission from Miki Tebeka:

Several modules can be invoked with -m and are pretty handy (json.tool, 
zipfile, tarfile ...).

There should be a section in the documentation that groups all of these "python 
-m" tools together. Something like 
http://pythonwise.blogspot.nl/2015/01/python-m.html

--
assignee: docs@python
components: Documentation
messages: 283190
nosy: docs@python, tebeka
priority: normal
severity: normal
status: open
title: Document all "python -m" utilities
type: enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com