On Sat, 12 Oct 2002 8:45 am, David Goodger wrote:
> I reckon that one produces a Python-specific doctree, and then
> chooses one of several transforms to produce generic doctrees.
A sound plan.
> By the way, I still vote for "static" introspection
> One of the tasks undertaken by the Python Source Reader is to
> decide what to do with docstrings. For each Python file, it
> discovers (from ``__docformat__``) if the input parser is
> "reStructuredText". If it is, then the contents of each docstring
> in that file will be parsed as such, including sorting out
> interpreted text (i.e., rendering it into links across the tree).
> If it is not, then each docstring will be treated as a literal
> This admits the posibility of adding other parsers *for
> docstrings* at a later date - which I suspect is how HappyDoc
> does it. It is just necessary to publicise the API for the
> Docstring class, and then someone else can provide alternate
> The output of the Python Source Reader is thus a Python-specific
> doctree, with all docstrings fully processed (as appropriate),
> and held inside <docstring> elements.
> The next stage is handled by the Layout Transformer.
> [What I call "stylist transforms". --DG]
> This determines the layout of the document to be produced - the
> *kind* or *style* of output that the user wants (e.g., PyDoc
> style, LibRefMan style, generic docutils style, etc.).
> Each layout is represented by a class that walks the
> Python-specific doctree, replacing the Python-specific nodes with
> appropriate generic nodes. The output of the Layout Transformer
> is thus a generic doctree.
It's going to have to be many generic doctrees though. That is, the "stylist
transforms" are likely to produce multiple output doctrees (an index, a
package page, multiple module pages, ...)
The resultant docutils doctrees are passed via normal transforms to the normal
I can see the multiple page output being useful for documenting larger volumes
of text - it'd be really nice if my Roundup documentation could all be parsed
in one go and then I could have inter-document references verified (and point
to specific anchors, oh my :), have the top-level Table Of Contents for all
documents generated, ...
> One specific thing to be decided, particularly for HTML, is
> whether one is outputting a "cluster" of files (e.g., as javadoc
Haven't looked at javadoc for a while - what's this mean?