Re: Plone developer manual

On 10/07/2009, at 7:50 AM, Gilles Lenfant wrote:

> Le 7 juil. 09 à 12:22, Mikko Ohtamaa a écrit :
>
>>
>> Hi,
>
> Hi,
>
>>
>> This is a notice for those who do not follow docteam list.
>>
>> "Developer manual" (final name is not yet decided) is a process to  
>> replace
>> the old "Common Plone programming recipes" tutorial. It is aimed to  
>> be a
>> community maintained effort to have  sane Plone developer  
>> documentation. It
>> will mainly consist of snippets of code to show how to use Plone  
>> API and
>> references to other documentation.
>>
>> Current effort is in collective SVN until Plone Help Center gets  
>> updated.
>>
>> For more information, read this post:
>>
>> http://n2.nabble.com/Plone-dev-manual-update-part-II-tp3218404p3218404.html
>>
>> See the current effort:
>>
>> https://svn.plone.org/svn/collective/collective.developermanual/ 
>> trunk/
>
> Great initiative.
>
> May I suggest to use Sphinx to structure all this (table of  
> contents, code coloration, search engine, glossary, index...) ?
>
> Most Python based projects - including Python itself - are  
> documented with Sphinx.
>
> http://sphinx.pocoo.org/
>
> I have a nice plone.org like skin for sphinx too.

The manual is only temporarily in svn until the new PHC is released.  
After that it will live there and Plone/PHC will do the contents,  
searching etc and allow it to be collaborated on via developers and  
non-developers alike.
Sphinx is a good solution that has been investigated [1] and it has  
the neat ability to write plugins that allow inclusion of  
documentation from other sources such as the actual code. It would be  
great to have that ability in a Plone context but what's more  
important right now is to get as many people making this an up to  
date, relevant document so we can help new developers avoid the pain  
of a steep learning curve.


[1] http://docs.garbas.si/plone-latest