[PYTHON DOC-SIG] Observations about gendoc.
Fri, 14 Feb 1997 07:57:19 -0600
______________________________ Reply Separator _________________________________
Subject: [PYTHON DOC-SIG] Observations about gendoc.
Author: Mark Hammond <MHammond@skippinet.com.au> at INTERNET
Date: 2/14/97 3:14 AM
Reply: Robin Friedrich
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?
I'm not sure .htp file format is important enough to provide
a separate plugin. The things gendoc is used for is not
likely to wind up as integrated python.org pages. It would be
easier to provide an HTMLgen resource class that matches the
* 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...
Good one. I like the first option as well. Although what we
do is run gendoc for two purposes -- one is user docs, but
the other is detailed docs that we slap into our DDS
(detailed design specifications). We thus need to retain the
current capability as well.
Thats all for today!
Is that today or yesterday, and if so what are you doing
tomorrow... oh forget it.
DOC-SIG - SIG for the Python Documentation Project
send messages to: firstname.lastname@example.org
administrivia to: email@example.com