Re: Help document Plone's API

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.
.




------------------------------------------------------------------------------
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