Python HTML Documentation Generators

[Pierre Rouleau]

Mikey At Work wrote:

> I'm looking for opinions on the several HTML documentation generators
> available for Python.  We're trying to standardize the documentaion used for
> an upcoming project.  Specifically, I'm looking for something very similar
> to Javadoc in both output and syntax (because most of our team members are
> very familiar with Javadoc).
> 
> I've pretty much narrowed it to either PythonDoc or epydoc, but wanted to
> ask the newsgroup's opinion before making a final decision. 

I have been using epydoc with reStructuredText instead of Javadoc and 
have found it quite useful.  I use reStructuredText myself (instead of 
Javadoc) because it is easy to format) so I can't comment on its Javadoc 
support.  It did not have any problem with its support for 
reStructuredText.  It is nice because you can create documentation wich 
contains URL linking to whathever you like and has support for 
'interpreted' links (links to class names, methods, functions etc...)

I have not used PythonDoc, but have used pydoc.  I prefer Epydoc over 
pydoc for its browsing capabilities.

I have also used Doxygen in the C++ world, and I would like to get its 
nice diagraming facilities incorporated in something like Epydoc 
(Doxygen is able to draw nice class hierarchy and class relationship 
diagrams).

   What are your opinions on
> documentation through docstrings vs documentation through comments?  

One very powerful advantage of docstring comments is the ability to 
provide testable examples that can be used as unit test code when you 
use the doctest module.  You cannot do this with comments.  Take a look 
at http://www.python.org/doc/current/lib/module-doctest.html.

With doctest and a simple markup language like reStructuredText (or 
probably JavaDoc) you can write very complete documentation that is 
extracted by Epydoc, formatted nicely in HTML (or other formats) and 
that can be tested for accuracy.

Pierre