[Doc-SIG] epydoc 1.1 release

[Edward Loper]

Guido van Rossum wrote:
> Would you mind comparing epydoc to the standard pydoc.py?

I compared epydoc to a number of other projects (pydoc is #1) at:

     <http://epydoc.sourceforge.net/relatedprojects.html>

But the short answer is that I see 3 main differences between epydoc
and pydoc:

   1. Epydoc produces html output that looks more professional and
      is easier to read and navigate.
   2. Epydoc supports the epytext markup language, which can be used to
      format docstrings, and to add information about specific fields,
      such as parameters and instance variables.  (But note that use of
      epytext is not required.)
   3. Pydoc provides excellent command-line (man-page style) and
      interpreter (pydoc.help) interfaces.

Pydoc is a great tool, and I would *not* advocate replacing it with
epydoc.  (Although I certainly wouldn't object to epydoc getting added
to the standard library, if enough people like it.  :)  Alternatively,
I wouldn't object to pydoc and epydoc getting merged, but it would be
quite an undertaking, because they're fairly different under the
hood.)

To be more specific, these are some of the important differences I see
between epydoc and pydoc:

- The output produced by epydoc is easier to read and navigate (in
   my opinion, anyway).
       - Epydoc produces a frames-based table of contents.
       - Epydoc provides a "show/hide private" toggle button.
       - Epydoc creates a "trees" page with class & module
         hierarchies.
       - Epydoc Creates an "index" page with term & identifier
         indices.
       - Epydoc includes a "help" page.
       - Epydoc includes a "breadcrumbs list" in the navigation bar,
         with pointers to the containing classes/modules/packages.
       - The navigation bar includes links to the "top" page and
         to the project's homepage.
       - Epydoc documents each class on its own page.
       - Epydoc uses external css stylesheets to allow for more
         customizable output.
       - Functions, methods, and variables are described with
         a shorter summary table and a longer details list.
       - Epydoc parses builtin function signatures.
       - Variable details includes variable type, optional description,
         and colorized value.
       - Lists of known subclasses, base class trees, etc.
       - Classes are divided into normal classes and exceptions.
       - Pydoc's layout wastes a lot of horizontal space.

- Epydoc supports use of the epytext markup language.
       - Epytext can be used to document parameters, variables, etc.
       - Inline markup can be used to mark italics, bold, monospace,
         documentation links, URLs, index terms, etc.
       - Epytext can be used to create ists, sections, and literal
         blocks.
       - Epytext colorizes doctest blocks.

- Epydoc can be used to check documentation completeness.

- Epydoc has a graphical interface (e.g. for windows users).

- Epydoc is fairly robust (e.g., it can document Zope 3).  I haven't
   actually tested the robustness of pydoc, though.

- Epydoc inherits documentation for undocumented methods whose
   signatures match the base class method.  (This can be disabled by
   adding a blank docstring to the undocumented method).

- Some advantages of pydoc are:
       - It provides links to the source code for each module.
       - It can be used from the command-line to view manpage-like
         docs.
       - It can be used from within python (pydoc.help)
       - It automatically creates intra-documentation links (you
         might see this as a positive or a negative, since it
         sometimes creates links where there shouldn't be links;
         epydoc is more conservative, and will only create links
         if you tell it to (with epytext markup).
       - It currently has better support for python 2.2-style
         types (with wrapper_descriptors, etc.).
       - It does some processing of comments.  Epydoc just uses
         docstrings.

I think that the best way to see the differences between their output is 
to navigate around the docs produced by each tool for the same code. 
The docs for the Python 2.2 standard library, from each tool, are at:

    pydoc: <http://web.pydoc.org/2.2/>
   epydoc: <http://epydoc.sourceforge.net/stdlib/>

Also, you might take a look at some of the docstrings written using 
epytext (e.g., see the source code for epydoc itself), and the 
documentation produced by those docstrings; or you could just look at "A 
Brief Introduction to Epytext" for a quick example:

     <http://epydoc.sourceforge.net/epytextintro.html>

-Edward