PYDOC replacement. (Was:Sorting attributes by catagory)

[Ron Adam]

Nick Vatamaniuc wrote:

> Ron,
> 
> Consider using epydoc if you can. Epydoc will sort the methods and it
> will also let you use custom CSS style sheets for the final HTML
> output. Check out the documentation of my PyDBTable module.
> http://www.psipy.com/PyDBTable
> 
> -Nick Vatamaniuc


Hi Nick,

I already have sorting and style sheets taken care of.  I'm just trying to 
get the content of each sub section correct at this point.  The overall 
frame work is finished.

I don't think Epydoc can replace the console help() output.  The site.py 
module imports help(), from pydoc.py.  That serves as the consoles 
interactive help mode.  When you type help() at the console, you are using 
pydoc.

Some of the differences...

Epydoc
------
     Output formats:
         - html files
         - graphs  (requires Graphviz)  I like this!
         - pdf files   (requires latex)

     * Requires explicitly generating files first.
     * Supports file parsing only instead of introspection.

Epydoc is more of a complete application and has many nice features such as 
the graphs and completeness checks, that will make it better than pydoc for 
creating more complete pre-generated html documents with less work.

Pydoc
=====
     Output formats:
         - live interactive console text
         - live interactive html with a local html server.
             * no files are generated.  (just in the browser cache)
             * supports custom CSS stylesheets

	(API data output...)
         - text
         - html page
         - html section     (for use in templates)
         - xml
         - reST      (not yet, but will be easy to do)

The reason for having additional output formats is it makes it much easier 
to use it as a tool to extract documentation from source code to be 
combined with existing more complete documentation.

I am planning on writing output formatters to return docutils and docbook 
data structures as well. With those, you will be able to convert to latex, 
pdf, and other formats.  The data formats for those are very close to what 
I'm using, so this should be easy to do.

Other side benefits of doing this is that some of the modules in pydoc have 
been generalized so that they can be used without pydoc.  The html server, 
and the document data and formatter classes, can be used independently of 
pydoc.

The overall total size has not increased much, and it is more modular, 
maintainable, and extendable.  Maintainability is a major concern for any 
library module or package.

Of course it will need to be approved first.  ;-)

Cheers,
    Ron