Re: Help document Plone's API

Dylan Jay wrote:
> On 23/05/2009, at 12:37 PM, Israel Saeta Pérez wrote:
> 
>> On Thu, May 21, 2009 at 2:59 AM, Martin Aspeli <[email protected] 
>>> wrote:
>>> Israel Saeta Pérez wrote:
>>>
>>>> I'd love to participate on that but I currently don't have the time
>>>> and won't have it until late June due to my exams. :-/
>>> I suspect we won't get anything moving until then, so if you do  
>>> want to
>>> own this, that'd be great. ;)
>> Cool!
>>
>>>> In the future I would like the API documentation to be generated
>>>> directly from the doctests and sphinx or similar tools would be very
>>>> helpful here.
>>> That's a different issue again. It'd be great to expose this.  
>>> However,
>>> there's too many doctests and interfaces and no structure (other than
>>> the arbitrary package structure of the code they're bundled with)
>>> that'll help people find what they need. If you look at that mindmap,
>>> many of the groupings sit across three or four packages.
>> Ok we can try to identify and document the API using the current
>> mindmap as basis. I prefer to work rather to argue, since we can
>> always copy-paste documentation inside a manual, doctests or whatever.
>> :)
> 
> I think martin is right in that I would think that most of it would be  
> written not autogenerated or included. Most existing doctests in plone  
> aren't going to be highlevel enough to run smoothly in a "programatic  
> plone" manual.  However it would be nice to use doctest format so we  
> could regression test the manual. We could then have the option to  
> include something if it was appropriate without having to cut and paste.
> 
> Then when the manual is done, the final html result, we just cut and  
> paste into plone.

If you want to do that for a section you're writing, feel free, of 
course. But the overhead of doing this is more than you may think. You 
need a lot of test setup, and it quickly becomes difficult to manage 
different sandboxes and test case layers. For some APIs it'll be quite 
easy. For others, it'll be pretty awkward, and require trade-offs in 
terms of readability to make the tests run.

And then, what do you do once someone goes to edit the copy on 
plone.org? It's not exactly good content management. ;-)

Martin

-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book


------------------------------------------------------------------------------
Register Now for Creativity and Technology (CaT), June 3rd, NYC. CaT 
is a gathering of tech-side developers & brand creativity professionals. Meet
the minds behind Google Creative Lab, Visual Complexity, Processing, & 
iPhoneDevCamp as they present alongside digital heavyweights like Barbarian 
Group, R/GA, & Big Spaceship. http://p.sf.net/sfu/creativitycat-com