[py-svn] r34769 - py/dist/py/documentation

[guido at codespeak.net]

Author: guido
Date: Mon Nov 20 11:30:44 2006
New Revision: 34769

Added:
   py/dist/py/documentation/apigen_comparison.txt
Log:
Document describing some other documentation generation tools.


Added: py/dist/py/documentation/apigen_comparison.txt
==============================================================================
--- (empty file)
+++ py/dist/py/documentation/apigen_comparison.txt	Mon Nov 20 11:30:44 2006
@@ -0,0 +1,103 @@
+Comparison of apigen with similar tools
+========================================
+
+Apigen is of course not the only documentation generation tool available for
+Python. Although we knew in advance that our tool had certain features the
+others do not offer, we decided to investigate a bit so that we could do a
+proper comparison.
+
+Tools examined
+---------------
+
+After some 'googling around', it turned out that the amount of documentation
+generation tools available was surprisingly low. There were only 5 packages
+I could find, of which 1 (called 'HappyDoc') seems dead (last release 2001),
+one (called 'Pudge') not yet born (perhaps DOA even? most of the links on the
+website are dead), and one (called 'Endo') specific to the Enthought suite.
+The remaining two were Epydoc, which is widely used [1]_, and PyDoctor, which is
+used only by (and written for) the Twisted project, but can be used seperately.
+
+Epydoc
+-------
+
+http://epydoc.sourceforge.net/
+
+Epydoc is the best known, and most widely used, documentation generation tool
+for Python. It builds a documentation tree by inspecting imported modules and
+using Python's introspection features. This way it can display information like
+containment, inheritance, and docstrings.
+
+The tool is relatively sophisticated, with support for generating HTML and PDF,
+choosing different styles (CSS), generating graphs using Graphviz, etc. Also
+it allows using markup (which can be ReST, JavaDoc, or their own 'epytext'
+format) inside docstrings for displaying rich text in the result.
+
+Quick overview:
+
+  * builds docs from object tree
+  * displays relatively little information, just inheritance trees, API and
+    docstrings
+  * supports some markup (ReST, 'epytext', JavaDoc) in docstrings
+
+PyDoctor
+---------
+
+http://codespeak.net/~mwh/pydoctor/
+
+This tool is written by Michael Hudson for the Twisted project. The major
+difference between this and Epydoc is that it browses the AST (Abstract Syntax
+Tree) instead of using 'live' objects, which makes that code that uses special
+import mechanisms, or depends on other code that is not available, can still
+be inspected.
+
+The tool is relatively simple and doesn't support the more advanced features
+that Epydoc offers, and since it's written basically only for Twisted, I don't
+think it will see a lot of development in the future.
+
+Quick overview:
+
+  * inspects AST rather than object tree
+  * again not a lot of information, the usual API docstrings, class inheritance
+    and module structure, but that's it
+  * rather heavy dependencies (depends on Twisted/Nevow (trunk version))
+  * written for Twisted, but quite nice output with other applications (except
+    that generating docs of the 'py lib' resulted in a max recursion depth
+    error)
+
+Quick overview lists of the other tools
+----------------------------------------
+
+HappyDoc
++++++++++
+
+http://happydoc.sourceforge.net/
+
+  * dead
+  * inspects AST
+  * quite flexible, different output formats (HTML, XML, SGML, PDF)
+  * pluggable docstring parsers
+
+Pudge
+++++++
+
+http://pudge.lesscode.org/
+
+  * immature, dead?
+  * builds docs from live object tree (I think?)
+  * supports ReST
+  * uses Kid templates
+
+Endo
++++++
+
+https://svn.enthought.com/enthought/wiki/EndoHowTo
+
+  * inspects object tree (I think?)
+  * 'traits' aware (see https://svn.enthought.com/enthought/wiki/Traits)
+  * customizable HTML output with custom templating engine
+  * little documentation, seems like it's written for Enthought's own use
+    mostly
+  * heavy dependencies
+
+.. [1] Epydoc doesn't seem to be developed anymore, either, but it's so
+       widely used it can not be ignored...