Python HTML Documentation Generators

[Andrew Bennetts]

On Tue, Feb 24, 2004 at 11:09:08AM -0500, Mikey At Work wrote:
> I'm looking for opinions on the several HTML documentation generators
[...]
> 
> I've pretty much narrowed it to either PythonDoc or epydoc, but wanted to
> ask the newsgroup's opinion before making a final decision.  Any experiences
> (good or bad) with either of these programs?  What are your opinions on

I've used epydoc (or rather, the Twisted project <http://twistedmatrix.com/>
uses it), and have no major complaints.  I've never used PythonDoc.

> documentation through docstrings vs documentation through comments?  Thanks
> in advance.

Docstrings are documentation intended for users of the module, class or
function that the docstring is documenting.  Comments are notes to future
implementors and maintainers about how piece of code works.  Roughly
speaking, docstrings are public, and comments are private.

-Andrew.