Python HTML Documentation Generators

Discussion in 'Python' started by Mikey At Work, Feb 24, 2004.

  1. 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
    Mikey At Work, Feb 24, 2004
    #1
    1. Advertising

  2. 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.
    Andrew Bennetts, Feb 25, 2004
    #2
    1. Advertising

  3. 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
    Pierre Rouleau, Feb 25, 2004
    #3
  4. 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?
    Brad Clements, Feb 25, 2004
    #4
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. anton muhin

    Python parser generators

    anton muhin, Nov 28, 2003, in forum: Python
    Replies:
    2
    Views:
    323
    Dave Kuhlman
    Nov 28, 2003
  2. The_Incubator
    Replies:
    4
    Views:
    433
    Linus Elman
    Jan 6, 2004
  3. Cameron Laird
    Replies:
    1
    Views:
    654
    Josiah Carlson
    Apr 3, 2004
  4. Kenneth McDonald
    Replies:
    2
    Views:
    729
  5. Replies:
    1
    Views:
    1,211
    Andy Dingley
    Sep 16, 2006
Loading...

Share This Page