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

Hi,

DocFinderTab -1. DocFinderTab must be replaced by proper external API
documentation. The reason why DocFinderTab exist is that Plone community
lacks proper practices to write and maintain code documentation.

When people come from other backgrounds (Java) and they are shown
DocFinderTab and told this is your best and only hope to find Plone code
documentation they will run screamingly away.

Run-time "in-system" doc generation is bad idea. Django tried it in some
point for template tags and it didn't work at all. Getting the system up and
running just to read docs for it is like climbing up to tree your bottom
first.

On Wed, Sep 2, 2009 at 12:23 PM, Alex Clark <[email protected]> wrote:

> Heh, OK well I never got to it. And it seems we don't have a consensus, so
> I'll leave it.
> But I would like to update it, so I'll take a look at Sphinx FWIW (yay, an
> excuse to look
> at Sphinx!)
>

We already have some Sphinx going on here:

https://svn.plone.org/svn/collective/collective.developermanual/trunk/source/

I specifically disabled automatic API doc/module doc generation, because
getting sane API doc output from Plone is little bit difficult.

I'd be interested to take a look how ZCML/Zope specific doc generators work.
For example http://apidoc.zope.org/++apidoc++/ generates documents for ZCML
directives, though it is obvious no one has never bothered to make useful
docstrings for them.

I think we could have some kind of "developer doc sprint" int the upcoming
conference to fix this problem once for all.

-Mikko

--
Mikko Ohtamaa
http://www.twinapex.com - Python professionals for hire

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