[py-svn] r34926 - py/dist/py/documentation
guido at codespeak.net
guido at codespeak.net
Thu Nov 23 23:44:59 CET 2006
Author: guido
Date: Thu Nov 23 23:44:58 2006
New Revision: 34926
Removed:
py/dist/py/documentation/apigen_comparison.txt
Modified:
py/dist/py/documentation/apigen.txt
Log:
Merging apigen documents.
Modified: py/dist/py/documentation/apigen.txt
==============================================================================
--- py/dist/py/documentation/apigen.txt (original)
+++ py/dist/py/documentation/apigen.txt Thu Nov 23 23:44:58 2006
@@ -106,6 +106,110 @@
action you run `py.test --session=L --apigen` in the root of the py lib; this
will result in documentation (in HTML) being written to /tmp/output.
+Comparison with other documentation generation 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...
+
Questions, remarks, etc.
-------------------------
Deleted: /py/dist/py/documentation/apigen_comparison.txt
==============================================================================
--- /py/dist/py/documentation/apigen_comparison.txt Thu Nov 23 23:44:58 2006
+++ (empty file)
@@ -1,103 +0,0 @@
-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...
More information about the pytest-commit
mailing list