[Zope3-dev] initial topics for z3 doc project

[kapil thangavelu]

hi holger,

i'm all for a whiz bang visual searchable autogenerated doc tool. but i 
really, really want the focus of the doc group at the sprint to be on 
narrative docs, that capture the semantics of zope3. mainly because, imo, z3 
can't afford to wait the way z2 did, in being an undocumented framework for 
years, granted in z3 is (imo) easier to come up to speed, because its got a 
whole lot less magic and bottom less holes. but migrating the masses to 
create a platform with growth, requires good docs that explain the concepts 
of the system. especially for z2 programmers, z3 is a paradigm shift, though 
much of less of one that zope in of and of itself is compared to some of the 
other open source web-app platforms. imo, the key to gaining new developers 
and quick productivity is an understanding of how the system works. api 
documentation is a great resource for developers, but if people don't 
understand how the system works its not all that useful in terms of helping 
them be productive. (at least i felt that way while staring at half-dozen 
logs coming out of a tomcat setup whilest simulatenously browsing javadoc, 
course it could have been the platform ;-).

most importantly, the sprint at infrae also represents at unparalleled 
opportunity i think to construct documentation in presence of a brain trust 
composed of some of the brightest minds in zopedom. the ability to ask other 
developers face to face regarding implementation/design mindset, is priceless 
in the wold of open source distributed development. plus we have the 
opportunity to capture immediate design philosophy from the other projects 
ongoing at the sprint. i would very much like this to be a sprint where more 
comes out being documented than what went in. in comparison, i think doc 
tools can be worked on anytime/anywhere without a loss of opportunity.

ok, thats my narrative doc spiel. onto autogenerated things... i really do 
like the capabilities of epydoc (as evidenced by the z3 docs @ 
http://www.objectrealms.net/zope3/api/public/), it does a really good job of 
capturing references and being able to cross link, and abstracting out 
presentation format. its not so hot an abstracting out the inspection bits, 
and their is quite a bit that is hardcoded in that regard. i conversed a bit 
with the epydoc author (edward loper) about the best/expedient way to go 
about interface integration... he responded..

"""
> kapil wrote
> honestly the biggest thing that would give me a big :-), would be support 
for 
> zope3 interfaces, as all the meat of the documentation is in them (most of 
> the class implementations of the intefaces say see the interface for the 
> details). i'm gonna try and patch epydoc to do it when i get some free time, 
> but i'm not quite sure where to start. basically i want to map the 
> documentation within the interfaces defined by the __implements__ attribute 
> in a class onto the method and class documentation for that class. any 
> hints/ideas on where to start?

This would probably go in epydoc/objdoc.py, which builds ObjDoc classes
that encapsulate the documentation for individual objects.  In particular, 
you'd probably want to extend FuncDoc (a child of ObjDoc) to check if it's 
documenting a method, and if so:
  - get the method's class (self._uid.cls().value())
  - get the class's interface (presumably this can be inherited.. Maybe
    use getattr(cls, '__implements__')).
  - check if the interface has a similarly named method (again, maybe
    use getattr so you don't have to deal with inheritance yourself?).
  - If you find a description of what the method implements, then add
    some field (eg implements) to the FuncDoc.  (i.e., add an instance
    variable _implements and a method implements() that returns it).
This is fairly similar to what currently happens with the "overrides" 
field, which is used to inherit documentation.  You might want to take
a look at FuncDoc._find_override.

You'd also need to extend ClassDoc in a similar way.  But that should be 
simpler:
  - get the classes interface.  Probably something like:
      getattr(self._uid.value(), '__implements__')
  - add a field (eg implements) to the class, pointing to the interface.

Then to actually see the results of your work, you'd also need to extend 
epydoc/html.py to print the docstring for the implements method.  The
easiest thing to do would probably be to "inherit" the implementation
docstring if the method/class is not documented itself.  This would be
in _func_summary and _func_details, and look something like:

  if not fdoc.documented() and fdoc.implements():
      fdoc = self._docmap.get(implements, fdoc)

If you wanted to merge the documentation, or to list the interface 
documentation separately, you'd need to do a little more work.  

"""

some other random pie in the sky thoughts i had on doc tools, abstract out the 
inspectors in epydoc so that they can be pluggable. another option might be 
to serialize the runtime analysis of a given package to static form (xml 
solves everything ;-), and distribute that along with packages and have it 
loaded onto a doc system along with the package (which would allow for 
additional non runtime analysis docs to be integrated with pkg distribution), 
and the doc system could index the docs and allow for searching. 

cheers,

kapil

(i've set my reply to header to an email address i'l be checking periodically 
while on vacation.)

On Thursday 07 November 2002 01:51 am, holger krekel wrote:
> Hi Kapil,
>
> kapil thangavelu wrote:
> > a quick a list of possible topics that could use some docs.
> >
> > initial audience, existing python friendly zope developers
> >
> > it might be nice to tie this into  some sort of story board ala the
> > job board tutorial.
> >
> > perhaps a zope startup story, life of a request, and developing a
> > sample poduct that uses all of the z3 framework product (perhaps extend
> > the job board presentation?). just tossing out some ideas to get some
> > discussion rolling, better/more suggestions wanted ;-)


you rock :-) i'm very happy to see any docs. mainly cause z3 can't afford to 
wait the way z2 did, in being an undocumented framework for years, granted in 
z3 its easier to come up to speed. but migrating the masses to create a 
platform with growth, requires good docs. i digress, you rock! 

> Good list.  I will only be preparing for the sprint/zope3-doc in the
> second half of november.  On my list is a first hack at integrating
> graphviz with epydoc (or another tool).  I have used it only at a higher
> level so please share code if you have some.
>
> also, i think it's worth trying to extract the basic information
> (inheritance, attributes, Implementation/Interface relations) at
> runtime.  In combination with an uses-everything Demo Product
> this should be doable.
>
> If all 'documentation' is available at runtime this makes it
> easier to have interactive search functions etc.  Maybe the
> Demo-Project project should really be a Zope3 product itself
> documenting itself.  Eat your own catfood.
> But that might mean we have to wait :-)
>
> As i have written an enhanced (documentation browsing) interactive
> cmdline completer i'd also like to integrate it with Zope3 and handle
> Interfaces and Adapters.  For this to work we'd need a
> monitor/debugging-facility that executes commands locally and talks
> via asyncchat to the readline completion handler.  You could login
> and talk to Zope3 and about Interfaces directly.  I'd like it.
>
> Hope to find more time for all that, soon, but don't hesitate to
> comment,
>
>     holger