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