[Doc-SIG] Re: epydoc 1.1 release

[Ka-Ping Yee]

Edward Loper wrote:
> 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/>

Nice work, Edward!  The output from epydoc is very beautiful.  The
pages produced by pydoc could be improved, though i think the major
differences between them come from a difference in design intent.
Put another way, epydoc and pydoc try to satisfy different constraints.

Here are pydoc's constraints so you can see what it was trying to achieve:

    (a) It tries to stick to "one module -> one file".
    (b) It tries not to present the same information twice.
    It tries to minimize dependencies...
        (c) on auxiliary files
        (d) on browsers
        (e) on code formatting

You may or may not agree that these constraints were good choices;
perhaps they seem extreme to you.  (There's a general philosophy of
minimalism at work here: i wanted the viewer to be able to see a lot
as quickly as possible.  It's also nice to be able to update the
doc file for a single module when you edit it, without having to
regenerate everything.)  epydoc relaxes some of these constraints,
and capitalizes on them to provide more functionality.

So, to revisit Edward's list of differences:

>       1. Epydoc produces a frames-based table of contents.
>       2. Epydoc provides a "show/hide private" toggle button.
>       3. Epydoc creates a "trees" page with class & module
>          hierarchies.
>       4. Epydoc Creates an "index" page with term & identifier
>          indices.
>       5. Epydoc includes a "help" page.
>       6. Epydoc includes a "breadcrumbs list" in the navigation bar,
>          with pointers to the containing classes/modules/packages.
>       7. The navigation bar includes links to the "top" page and
>          to the project's homepage.
>       8. Epydoc documents each class on its own page.
>       9. Epydoc uses external css stylesheets to allow for more
>          customizable output.
>      10. Functions, methods, and variables are described with
>          a shorter summary table and a longer details list.
>      11. Epydoc parses builtin function signatures.
>      12. Variable details includes variable type, optional description,
>          and colorized value.
>      13. Lists of known subclasses, base class trees, etc.
>      14. Classes are divided into normal classes and exceptions.
>      15. Pydoc's layout wastes a lot of horizontal space.
[...]
>      16. Epydoc supports use of the epytext markup language.

Some of these can be explained in terms of the differing constraints;
others are just deficiencies (missing features in pydoc).

Why doesn't pydoc do...

     1? Because of (d).
     2? Because of (a).
     3? Instead of one big page of trees, pydoc has little class
        trees on each module's page.
     4? Missing feature.
     5? Missing feature / didn't think it would be necessary.
     6? pydoc does do this (breadcrumb links are in the header bar).
     7? pydoc does do this (index link is in the header bar).
     8? Because of (a).
     9? Because of (c).
    10? Because of (b).
    11? Missing feature / didn't know there was an established convention.
    12? (e): didn't want to impose a standard for describing variables.
        In most cases the type is redundant (the type is evident from
        the repr) and pydoc tends to be minimal about the use of space.
    13? Missing feature.
    14? Missing feature.
    15? The bars on the left were intentionally placed there to provide
        context (as you scroll down a long page, it may not be visible
        what section you're in).  You could say they're too fat though.
    16? Because of (e).


-- ?!ng