[Docutils-develop] Re: [Doc-SIG] looking for prior art

[Doug H. <do...@he...>]

On Friday 06 December 2002 9:47 pm, David Goodger wrote:
> Doug Hellmann wrote:
> >
> > Why perform all of those transformations?  Why not go from the AST
> > to a generic doctree?  Or, even from the AST to the final output?
>
> I want the docutils.readers.python.moduleparser.parse_module()
> function to produce a standard documentation-oriented AST that can be
> used by any tool.  We can develop it together without having to
> compromise on the rest of our design (i.e., HappyDoc doesn't have to
> be made to work like Docutils, and vice-versa).  It would be a
> higher-level version of what compiler.py provides.

That part makes sense.

> The Python reader component transforms this generic AST into a
> Python-specific doctree (it knows about modules, classes, functions,
> etc.), but this is specific to Docutils and cannot be used by HappyDoc
> or others.  The stylist transform does the final layout, converting
> Python-specific structures ("class" sections, etc.) into a generic
> doctree using primitives (tables, sections, lists, etc.).  This
> generic doctree does *not* know about Python structures any more.  The
> advantage is that this doctree can be handed off to any of the output
> writers to create any output format we like.

Ah.  I handled that differently in HappyDoc.  Instead of building another 
data structure, I set up the API for the formatters to have methods that do 
things like start/end a (sub)section, start/end a list, etc.  The primary 
implementation is an HTML formatter that produces tables, but there are other 
formatters.  The docset is then responsible for calling the right formatter 
method when it wants it.  Having the docset and formatter separate makes 
things more complicated than I expected, so in HappyDoc 3.0 there will just 
be one plugin system.  

There is a new scanner which walks the input directory building a tree of 
scanned files, doing optional special processing for each based on mimetype.  
For text/x-python files, the file is parsed and information about classes, 
etc. are extracted.  The output formatter walks the resulting tree, also 
doing mimetype-based processing for each file.  HTML and image files will be 
copied from input to output.  Text files are converted using the docstring 
converter, and the parse results from Python modules are used to generate new 
HTML output files.

I've got the scanner done, and am working on the output formatter code now. 

Doug