[PYTHON DOC-SIG] Observations about gendoc.

[Robin.K.Friedrich@USAHQ.UnitedSpaceAlliance.com]

______________________________ 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 
        python.org style. 
     
* 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.
        
        -Robin
Mark.
_______________

_______________
DOC-SIG  - SIG for the Python Documentation Project

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