[Doc-SIG] htmldoc.py and inspect.py

[Ka-Ping Yee]

Hi everyone.

I'm writing to announce that i've posted my current work on
a documentation generator.  Those of you who were in the
doc-sig room at IPC8 may remember the example i showed.  Quite
a few people seemed to like it and i promised to produce the
script -- so here i am trying to make good on my promise.

Done:
    - documentation of user modules, classes, methods, and functions
    - documentation of built-in functions
    - automatic hyperlinking when classes and methods are mentioned
    - detection of leading comments when no docstring is present
    - overview of class inheritance tree within a module
    - generation of HTML files from the command line
    - all generated files are SGML compliant! :) :) (HTML 4.0 Transitional)

To do:
    - no directory/package indexing yet
    - simple HTTP server (so you can get fresh docs on your own modules)

As there are still items on the to-do list it's not entirely
done yet -- but there is enough done to work fairly well, and
i wanted to give you a chance to look at it and let me know
what you think.

The modules are:

    http://www.lfw.org/python/htmldoc.py
    http://www.lfw.org/python/inspect.py

Fred: i would like to seriously propose this to go with 1.6.
Will you consider it?

The "htmldoc" module is actually quite small (only about 300
lines) as most of the hard work has been factored out into
the "inspect" module -- a non-HTML-specific collection of
routines for getting all kinds of information out of your
Python objects.  My favourite routine in "inspect" is
inspect.getsource(object), which can get you the source code
for a function, method, or class.

The IPC8 example i showed is at

    http://www.lfw.org/python/SocketServer.html

That output was produced by a script called "manpy.cgi" that
i wrote at work, and unfortunately that meant the script could
not be distributed outside of my company.  The new script
produces very similar output, but it has been rewritten from
scratch on my own time -- which means (a) it's completely
unencumbered by any IP claims; and (b) i got to make it a
little bit cleaner.

I have run the new script over the Python 1.5.2 standard
library.  Please browse the results at

    http://www.lfw.org/python/htmldoc/

I welcome your feedback!

Thanks,



-- ?!ng

"To be human is to continually change.  Your desire to remain as you are
is what ultimately limits you."
    -- The Puppet Master, Ghost in the Shell