[Doc-SIG] list of tools for the doc-sig page

[Edward Loper]

I think that the python doc-sig page <http://www.python.org/sigs/ 
doc-sig/> should include a list of the tools that are currently 
available for automatically extracting API documentation (pydoc, 
HappyDoc, docutils, etc).  There are 11 tools that I know of, but there 
might be more.  I wrote up a table summarizing the tools that I know of, 
so it should be possible to just copy/paste the HTML to the doc-sig page 
(who maintains that page?).  Or if people think that my table should be 
changed, or that the information would be better presented as a list of 
descriptions, etc., then we could do that..  The table that I put 
together is (temporarily) available at:

     <http://www.cis.upenn.edu/~edloper/python_api.html>

I'll also include a slightly reduced/summarized text version of the 
table below, in case that's more convenient for some people.

Also, if any of the information I listed is incorrect/incomplete, or if 
I left out any tools that you know of, please let me know.  I think we 
should try to make this list as complete as possible.

-Edward

===========================================================================
Tool     |Markup          |Output    |License         |Status      |Notes
          |Language(s)     |Format(s) |                |            |
=========*================*==========*================*============*=======
Crystal  |StructuredText  |HTML      |unspecified     |unmaintained|D, P
---------+----------------+----------+----------------+------------+-------
doc.py   |doc_string      |HTML      |doc.py license  |unknown     |D, P
---------+----------------+----------+----------------+------------+-------
Docutils |reStructuredText|(none yet)|Python License  |under       |D, P
          |                |          |                |construction|
---------+----------------+----------+----------------+------------+-------
Easydoc  |Javadoc-like    |HTML      |GPL             |stable      |D, P
---------+----------------+----------+----------------+------------+-------
epydoc   |epytext         |HTML      |IBM License     |stable      |D, I
---------+----------------+----------+----------------+------------+-------
gendoc   |StructuredText  |HTML      |gendoc license  |unknown     |D, P
          |                |plaintext |                |            |
          |                |MIF/MML   |                |            |
---------+----------------+----------+----------------+------------+-------
HappyDoc |StructuredTextNG|HTML      |HappyDoc License|stable      |C, D, P
          |StructuredText  |DocBook   |                |            |
          |plaintext       |Dia       |                |            |
          |raw             |          |                |            |
---------+----------------+----------+----------------+------------+-------
pydoc    |plaintext       |HTML      |Python License  |stable      |D, I
          |                |man       |                |            |
---------+----------------+----------+----------------+------------+-------
Pythondoc|StructuredText  |HTML      |Pythodoc License|beta        |D, I
          |                |XML       |                |            |
---------+----------------+----------+----------------+------------+-------
Teud     |plaintext       |HTML      |Teud License    |unknown     |D, I
          |                |XML       |                |            |
---------+----------------+----------+----------------+------------+-------
XIST     |XML             |HTML      |Python License  |unknown     |D, I
===========================================================================

Key:
   Tool: The name of the API documentation generation tool. Link is to
       the tool's homepage.
   Markup Langauge(s): The markup language(s) that can be used within
       docstrings. Links are to the markup languages' definitions.
   Output Format(s): The type(s) of output that the tool can
       produce. Links are to examples of the output produced by the
       tool for each format.
   License: The license that the tool is distributed under. Link is to
       the license itself.
   Status: The current status of the tool.
   Notes:
     C: Documentation is generated from comments.
     D: Documentation is generated from docstrings.
     P: Documentation is generated by parsing Python files.
     I: Documentation is generated by introspection.