[Doc-SIG] Re: epydoc 1.1 release

[Ka-Ping Yee]

On Thu, 31 Oct 2002, Edward Loper wrote:
>    - a markup language that is very simple and clean, and has no hidden
>      "gotcha" cases.

I like the simplicity of epytext.

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

Oh, i didn't realize that.  Well done.

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

I guess it just made sense to me at the time not to have too many files.
Navigating with the scroll bar is faster than loading a new page.  It
seemed convenient to have module-level functions and small utility
classes kept together with the classes that use them.  But i see good
arguments both ways; in the end it's just a judgement call.

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

Yeah, exactly.  I didn't want to deal with tracking dependencies among
the files to figure out what to update when a module was changed, and
it seemed wasteful to redo everything.  If i were to write pydoc today,
i'd probably use a stylesheet, though.  CSS support has improved a lot.

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

Yes, the summary tables are quite nice.


-- ?!ng