Re: Let's turn off api.plone.org.

On Fri, Aug 21, 2009 at 4:06 PM, Wouter Vanden Hove <
wouter-8+Rs0Pd0Jda191EdcfFfGdi2O/[email protected]> wrote:

> Dylan Jay wrote:
>
>
> > I think the closest is in Mikko/collective new developer documentation
> > even though it's not published on plone.org yet.
>
> It could have been, but I regret the decision to not base it on Sphinx.
> Nearly all python projects use Sphinx nowadays for *developer*
> documentation.


(Shh: secret. collective.developermanual runs on Sphinx nowadays. But don't
tell anyone ;)

Seriously... manual files are just bunch of restructured text docs. You can
very very easily build HTML Sphinx manual offline or publish them in
plone.org.

If someone helps me to stick Sphinx index.txt files together and fix some
resST errors the manual is good-to-know:
https://svn.plone.org/svn/collective/collective.developermanual/trunk/source

I'll plan to create upload script which either pushes docs themselves as
reST to plone.org or puts them though Sphinx HTML generator first.

More serious problem regarding the API documentation that the classes itself
don't document themselves properly. There won't be API documentation until
API is documented.

* All ZCML documentation (apidoc.zope.org) lack examples

* There is no way to generate zope.event event list, since event interfaces
don't tell where the event is used

* There is no way to generate event subscriber list

* There is no way to generate stock view list since view classes are
uncommented

* and so on...

Autogeneated API docs don't make sense in Plone world until someone, who
actually knows the code, goes through the code and inserts at least one line
description to each class/interface/zcml/event/GenericSetup
XML/template/whatever.

Today I encountered such a challenge as there was OFS package in the core of
Zope doing lots of lots of things. This package lacked README.txt or any
sort of readable developer documentation. Well... that's ok, but no one
actually knowns what acronym OFS means anymore. It's bad that the system
runs on magic whose name no one recalls anymore... ;)

Happy weekend,
-Mikko

------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day 
trial. Simplify your report design, integration and deployment - and focus on 
what you do best, core application coding. Discover what's new with 
Crystal Reports now.  http://p.sf.net/sfu/bobj-july

_______________________________________________
Plone-docs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/plone-docs