Python HTML Documentation Generators

[Mikey At Work]

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. Any experiences
(good or bad) with either of these programs? What are your opinions on
documentation through docstrings vs documentation through comments? Thanks
in advance.

 

[Andrew Bennetts]

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

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.

 

[Pierre Rouleau]

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

 

[Brad Clements]

Has anyone tried PBS ?

http://swag.uwaterloo.ca/pbs/examples/

The Software Bookshelf is a set of software tools for visualizing and
navigating information that represents large software systems. PBS is a
portable version of this software.

It looks a little old, but the visualization of Linux is interesting.

I've also taken a look at Shrimp

http://shrimp.cs.uvic.ca/

I think epydoc and other doc tools could extract the data that these two
tools need. Anyone else try these?