[PYTHON DOC-SIG] Observations about gendoc.

Mark Hammond MHammond@skippinet.com.au
Fri, 14 Feb 1997 19:14:27 +1000

Im starting to look into some of those changes I mentioned before.  
On my way Ive noticed a few things...

All comments appreciated.  I'll take a lack of objections as implicit 
approval to hack these changes, and submit them back :-)

* .htp files.  Is Ken on this list?  www.python.org wants .htp files, 
which a script then converts to html.  Whats the best way to tackle 
this?  Just setup a "template" to make it look like the finished 
.html, and skip the conversion process?

* Exceptions - It looks like much of this code pre-dates a useful
traceback module.  Some handlers print sys.exc_type, sys.exc_value
etc (syntax error handling comes to mind) - should these be upgraded
to print the full traceback?

* Private Methods - I would find it useful if there was a mode which 
says "use Private Methods, but only if they have a docstring.  ie, 
the existance of a docstring dictates its private-ness.  In fact, 
maybe a more general "only export is docstring'd" flag - regardless 
of the leading "_".  Personally, I prefer the first option better...

Thats all for today!

Mark Hammond - MHammond@skippinet.com.au 
Check out Python - _the_ language for the Web/CGI/Windows/MFC/Unix/etc
<http://www.python.org> & <http://www.python.org/ftp/python/pythonwin>

DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org