[Doc-SIG] Automated __doc__ string processing systems

[Ka-Ping Yee]

Hi, Edward.

On Sun, 4 Mar 2001, Edward D. Loper wrote:
> I've recently been reading up on the status of automated documentation
> extraction from formatted inline comments in Python.  It sounds like
> one day, a tool for extraction may become part of the standard library.

Yes -- just this past week, pydoc became a part of the Python 2.1 beta
distribution.  Two new modules were added:

    inspect.py - Get useful information from live Python objects.

    pydoc.py - Generate Python documentation in HTML or text for
        interactive use.

They are separately available at

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

and documented at

    http://www.lfw.org/python/inspect.html
    http://www.lfw.org/python/pydoc.html

The Python modules are written to work with any version of Python
from 1.5.2 up, so you should be able to just download the two files
and run them.

pydoc intentionally avoids the issues of syntax for formatting
docstrings, as that has historically been a contentious issue.

I looked at epydoc -- it's nice work, and your essay was a good
survey of the issues and ideas.  I hope that pydoc's inclusion
doesn't disappoint you, as you have clearly done a lot of hard
work on epydoc, and that pydoc proves worthy of its blessing.
I hope to learn from what you've done as we take pydoc forward.


-- ?!ng

"The biggest cause of trouble in the world today is that the stupid people
are so sure about things and the intelligent folk are so full of doubts."
    -- Bertrand Russell