[Doc-SIG] Re: epydoc 1.1 release
Ka-Ping Yee
python-doc@zesty.ca
Wed, 30 Oct 2002 23:15:45 -0800 (PST)
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