[PEAK] A small coding project for anyone desiring to contribute

[Phillip J. Eby]

At 02:42 AM 9/22/04 -0400, Duncan McGreggor wrote:

>On Sep 22, 2004, at 12:46 AM, Phillip J. Eby wrote:
>
>>I've been thinking that it would be really nice to have a "quick 
>>reference guide" to PEAK.
>>
>>Specifically, it would be nice to have a script that could spit out, for 
>>any given PEAK API, a list of the names defined in that API, whether each 
>>name was a class or function, and a one-line description.
>
>I just did a quick hack... is this heading in the right direction?

Yes, with some formatting changes.  There should be a heading for each API, 
rather than putting the info on the same line, e.g.:

config

   CreateViaFactory  (Class)
     'IRule' for one-time creation of target interface using FactoryFor()

   IConfigSource (Interface)
     Something that can be queried for configuration data

I wonder, though, if there's also some way we can define some kind of 
category mechanism, such that there can be subheadings like "Attribute 
Descriptors", that then lists all the items therein, e.g.:


binding

   Attribute Descriptors

     Make  [Attribute]
       'Make(recipe)' - Construct a value and cache it

     Obtain  [Attribute]
       'Obtain(componentKey,[default=value])' - finds/caches a needed component


   Component Hierarchy Navigation

      getParentComponent(component)  [Function]
        Return parent of 'component', or 'None' if root or non-component

      iterParents(component, max_depth=100)  [Function]
        Iterate over all parents of 'component', up to 'max_depth'


Perhaps I could do this by adding a category attribute of some kind to the 
classes and functions, and/or having a declaration mechanism.  For example, 
maybe I'd do:

     from peak.util import docindex as doc
     doc.publish_to("peak.binding.api")

     ATTRIBUTE_DESCRIPTORS = doc.Category(1, "Attribute Descriptors")
     NAVIGATION = doc.Category(2, "Component Hierarchy Navigation")
     # etc...

     [doc.begin(ATTRIBUTE_DESCRIPTORS)]

     class Obtain:
         ...

     [doc.begin(NAVIGATION)]

     def getParentComponent(component):
         ...

     [doc.end()]

and so on.  This could then build up an index in the API module, so that 
all the other tools would need to do is read the index and generate 
item-specific docs.  Only items listed in '__all__' would get published, 
and so on.  Maybe there'd even be a 'defmodule()' used at the package level 
to define what modules should be listed.

Hm.  I wonder if I could also do the same *within* classes?  After all, 
some large classes in PEAK have huge method/attribute lists, that then 
break down into different interfaces or areas of functionality.

This is really interesting, because this approach could work around lots of 
problems in the current crop of Python documentation tools: the ones that 
use imports and introspection lose critical ordering and grouping 
information, while the ones that scan source code lack certain other kinds 
of "intelligence".

Indeed, I can see how this technique could grow into a complete API 
documentation tool with full developer control over how things are 
categorized and what's documented, including many things that current tools 
miss.

But anyway, I've digressed quite a bit here.  For now, it would just be 
handy to be able to generate a text listing without any categories, of just 
functions, classes, and interfaces.  Such a list could then be dumped into 
e.g. the Wiki, or better yet, dumped into a README.txt in each package 
directory.  HappyDoc, the tool we currently use to generate references, 
will then turn it into the HTML front page of that package's description.

It'll probably take some tweaking of the text format to get HappyDoc to do 
exactly what we want.  In particular, we'll want the names to link directly 
to the class or function doc, so that people won't have to browse 
module-by-module to find these items.  But I can play around with doing 
that, if you've got a basic script to dump out plain text.


>I ran into some issues (unexplored) with the types that I put in the 
>following list:
>
>BAD_TYPES = ['int', 'str', 'PropertyName', 'PathSyntax', 'CompoundName', 
>'_NullConfigRoot']

One way to handle this is to define an interface, IDocumentable, with 
methods for getting the "type" or "category" the object should be in.  You 
then define adapters that implement the interface for different types such 
as InterfaceClass, type, and so on.  That way, the adapters can provide 
names like "Interface" and "Attribute Descriptor" instead of 
"InterfaceClass" and "AttributeClass".  This would also allow you to 
distinguish other behaviors like whether there's a function signature to 
include.

(Btw, unrelated note: on Wiki pages where you're quoting me, please include 
more context, especially a link to the original email, but also a paragraph 
or two of whatever I'm responding to.  Out-of-context quoting makes my 
statements look overbroad to other readers, not to mention confusing in 
many cases.  Indeed, it would also be better to just take a single pithy 
sentence or paragraph as an excerpt, and then point people to the original 
mail.  That is, either quote a lot less or a lot more than you're currently 
doing.  Thanks.)