Kendall Clark wrote:
> jeffrey> 1. Documentation - it would help to see what core set(s) of
> jeffrey> methods make up servlet use, and which methods are
> jeffrey> particular to special servlet implementations.
> and toward this same end --
> I think it would help if someone could run pydoc (or one of the python
> documenting tools) over the Webware source and put the result on the
> site. I've been working on some "So you wanna write a webware app"
> notes, for a series of articles I'm gonna sell to O'Reilly, and the
> existing API documentation is rather unhelpful. Sure, I can 'just use
> the source', which I'm doing. But I find the combo of API docs and the
> source the best approach, personally.
> I especially like Ka-Ping Yee's API (HTML) output; any chance we can
> get that on the Webware site?
Let's not make this a one-off. Instead, pydoc or other documentation tools
should be run on the Python source automatically as part of running "python
install.py" (or "python setup.py install" in the future).
"python install.py" already makes some attempt at generating summaries from
the source files, but I don't find the generated output to be very useful.
It doesn't include the docstrings, for example. Here's the kind of output
it generates currently:
If anyone wants to improve these generated summaries, I'd be very happy to
accept the patches.
Then, it's a matter of improving the docstrings. We should strive to have
all methods that are part of the public interface be clearly identified as
such, and also to be well documented. (And tested via automated tests.)
From: Kendall Clark <kendall@mo...> - 2002-04-09 16:03:31
>>>>> "geoffrey" == Geoffrey Talvola <gtalvola@...> writes:
geoffrey> Let's not make this a one-off. Instead, pydoc or other
geoffrey> documentation tools should be run on the Python source
geoffrey> automatically as part of running "python install.py" (or
geoffrey> "python setup.py install" in the future).
Sure, I was working up to that. :>
I tried to run pydoc (from 2.2) against my Webware installation and it
failed to generate *any* docs -- I thought it worked off docstrings
and parsing classes/methods/functions, but it didn't seem to like
Webware install tree at all.