[Doc-SIG] Re: epydoc 1.1 release

[Edward Loper]

Ka-Ping Yee wrote:
> 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

Just for comparison, some of epydoc's constraints were:

   - pretty/easy-to-navigate html output.
   - support for documenting "fields" (parameters, variables, etc).
   - a markup language that is very simple and clean, and has no hidden
     "gotcha" cases.
   - a markup language that is powerful enough for most people's needs
     when writing API docs.  (Well, at least for *my* needs :) )
   - robustness.
   - minimized dependencies on browsers (note that epydoc output
     looks quite good under text browsers like links, and old versions
     of netscape/ie).
   - maximized information density (though perhaps not as strongly
     maximized as it is for pydoc).

> 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.  

I can appreciate minimalism, and I stand by my statement that pydoc is a 
great tool that fills a very useful niche.  I use it for its 
manpage-style output all the time.

 >>      1. Epydoc produces a frames-based table of contents.
 >      1? Because of (d). [d=no dependency on browsers]

But note that the use of frames is totally optional for the viewer.

>>      3. Epydoc creates a "trees" page with class & module
>>         hierarchies.
 >      3? Instead of one big page of trees, pydoc has little class
 >         trees on each module's page.

This makes it harder to see how classes defined in different modules 
relate to each other.

 >>       2. Epydoc provides a "show/hide private" toggle button.
 >      2? Because of (a). [a=one module/file]
 >>      8. Epydoc documents each class on its own page.
 >      8? Because of (a). [a=one module/file]

What's the reasoning behind the one module/file criteria?  I decided to 
put each class and method on its own page, because they seemed to be 
about the right sized conceptual "chunk."  Also, this means that the 
"nesting" of objects on any given page is just 1-deep (modules->vars, 
modules->classes, classes->methods, classes->vars, etc.), whereas one 
module/file gives 2-deep nesting (modules->classes->methods, etc).

 >>      9. Epydoc uses external css stylesheets to allow for more
 >>         customizable output.
 >      9? Because of (c). [c=no dependance on auxilliary files]

The stylesheet can be safely ignored, and the pages still come out 
looking pretty nice.  Is the reasoning behind this that you want to be 
able to grab a single html file by itself, and copy it somewhere?  This 
suggests that one difference between pydoc and epydoc is that I think of 
the set of docs created by epydoc as a single coherent whole (that 
shouldn't every really be split up), whereas it seems like you think of 
the docs created by pydoc as a set of related but independant files.

 >>     10. Functions, methods, and variables are described with
 >>         a shorter summary table and a longer details list.
 >     10? Because of (b). [b=no repetition of information]

That seems pretty reasonable, but if the docstrings get long, it can 
make it hard to scan through and quickly see what a module/class provides.

 >>     11. Epydoc parses builtin function signatures.
 >     11? Missing feature / didn't know there was an established
 >         convention.

I seem to remember seeing a convention written in the python style guide 
somewhere that builtin functions should start with a 1-line signature 
(since the signature can't be divined via inspection).  This convention 
is certainly followed by __builtin__, sys, os, os.path, etc.

Feel free to rip out my algorithm and adapt it to your own code.  It's 
in epydoc.objdoc.FuncDoc._init_builtin_signature, on line 1313 of 
epydoc/objdoc.py.  It currently handles just about everything except for 
"zip" which I argue doesn't quite follow the normal conventions:

     zip(seq1 [, seq2 [...]]) -> [(seq1[0], seq2[0] ...), (...)]

(I think my algorithm would recognize it with another comma either 
before or after the inner "[".)

On the subject of ripping code from epydoc, there's other code that you 
might want to rip for inspect.py.  E.g., see 
epydoc.uid._find_builtin_obj_module and 
epydoc.uid._find_function_module, which are more robust than the 
corresponding functionality provided by inspect.py.

>>     12. Variable details includes variable type, optional description,
>>         and colorized value.
 >     12? (e): didn't want to impose a standard for describing
 >         variables. [e=minimize dependencies on code formatting]

I think this falls under the category of things you can do with fields, 
if you want to allow fields (which pydoc doesn't, for reasonable reasons).

 >         In most cases the type is redundant (the type is evident from
 >         the repr)

I think that type info can be pretty useful in some cases -- it's not 
always apparent from the repr.  Also, this lets me provide a link to the 
type, when it's a class.

 >         and pydoc tends to be minimal about the use of
 >         space.

I find epydoc's representation of variables much easier to read 
(multiline strings, colorized regexps, etc), but there's certainly no 
question that pydoc's representation is more compact. :)

>>     15. Pydoc's layout wastes a lot of horizontal space.
 >     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.

Yeah, I think they're too fat.  And when viewing the docs in text 
browsers, they're just dead space.

 >>     16. Epydoc supports use of the epytext markup language.
 >     16? Because of (e). [=no dependancy on code formatting]

I think that this is a significant difference in goals for the two 
projects.  But as I said on my related projects page, I think this may 
be one of the reasons that pydoc was able to become widely accepted.  Of 
course, epydoc will treat all docstrings as plaintext if you tell it to. 
  (Well, to be precise, if you use "--docformat plaintext", then the 
format for docstrings will default to plaintext, unless overridden on a 
per-module basis by the __docformat__ variable.)

-Edward