Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Python HTML Documentation Generators

Reply
Thread Tools

Python HTML Documentation Generators

 
 
Mikey At Work
Guest
Posts: n/a
 
      02-24-2004
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.

--
Mike


 
Reply With Quote
 
 
 
 
Andrew Bennetts
Guest
Posts: n/a
 
      02-25-2004
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.


 
Reply With Quote
 
 
 
 
Pierre Rouleau
Guest
Posts: n/a
 
      02-25-2004
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/li...e-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

 
Reply With Quote
 
Brad Clements
Guest
Posts: n/a
 
      02-25-2004
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?




 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
converting XSD documentation to HTML documentation kev.sully@gmail.com XML 1 09-16-2006 12:09 PM
Python documentation: How about structured documentation? Looking for comments/suggestions Kenneth McDonald Python 2 05-06-2004 04:11 AM
Principles of documentation (was: Python Documentation Blows!) Cameron Laird Python 1 04-03-2004 06:54 PM
Scripting C++ Game AI object using Python Generators The_Incubator Python 4 01-06-2004 12:17 AM
Python parser generators anton muhin Python 2 11-28-2003 07:37 PM



Advertisments