[Docutils-develop] Re: sandbox/tibs/pysource/notes thoughts.txt

[Richard J. <rj...@ek...>]

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

+1


> 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
> block.
>
>   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
>   plugins.
>
> 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 
HTML writer.

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

Haven't looked at javadoc for a while - what's this mean?


    Richard