[PEAK] Organizing documentation of Python code

Ian Bicking ianb at colorstudy.com
Thu Sep 23 12:17:45 EDT 2004


Phillip J. Eby wrote:
>> Unfortunately it can't read comments at all.  But otherwise all the 
>> interesting information is there.  Right now it is creating a DOM, 
>> which is the docutils DOM plus some source-code-specific nodes.  It 
>> needs something to translate that DOM into a standard docutils DOM, 
>> which can then be rendered.  It also needs a lot of work and thought 
>> to deal with inter-module references, but it would still be useable 
>> without that. Oh, and subclassing -- that's a hard one too (being able 
>> to display a picture of a class's methods, including all superclass 
>> definitions). And, for PEAK, you'll probably want to be able to extend 
>> the whole thing for special PEAK constructs.
> 
> 
> Right - and that's *really* hard to do with a source processing tool, 
> because it can't figure out that 
> 'protocols.advise(instancesProvide=[IFoo])' actually means something we 
> want to document specially.
> 
> The advantage of object-extraction tools (in principle) is that this 
> kind of information is extractable, as long as you have an extensible 
> way to control its extraction.  The current crop of object extractors 
> aren't capable of that, and I had been putting off implementing my own 
> because of the sequencing/categorization issues.  As I said, this idea 
> was just the thought that I could get sequencing and categorization by 
> "decorating" modules with calls to a small documentation API.

Or, you could do a hybrid.  Load the objects, then do minimal parsing on 
the module, adding attributes to objects you loaded to indicate their 
order, and perhaps some other small things, like finding interstitial 
docstrings.  That seems a lot easier than trying to do *everything* 
through source parsing, which starts to get really hard at some point, 
and it gives you the extra information that you want.

   Ian



More information about the PEAK mailing list