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

On 2009-09-02, Mikko Ohtamaa <[email protected]> wrote:
> 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.

This is all debatable, and I don't care :-) This thread is about what to
do with api.plone.org.

> On Wed, Sep 2, 2009 at 12:23 PM, Alex Clark <[email protected]> wrote:
> 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.

Yup, that's the point of this thread. Why generate meaningless API docs? The
answer is, some folks are saying "we like our API docs" :-). Fine with me.
I'm going to generate some (arguably meaningless) Sphinx docs for api.plone.org 
"just for kicks" (because some folks still think it is a good idea, or at least not
a bad idea, and at the very least they don't want to "do nothing" i.e. turn it off).

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

++apidoc++ is part of the ZTK (i.e. zope.app.apidoc.codemodule.interfaces.IAPIDocRootModule)
and we could have that in Plone, I think, if someone does the work to port it to Five.
(I'm not sure how you could be a fan of ++apidoc++ but not DocFinderTab, but again
for the purposes of this thread I don't care :-p, I'm just trying to figure out what 
to do with api.plone.org ;-)

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

I won't hold my breath ;-) But yeah.

>
> -Mikko
>
> --
> Mikko Ohtamaa
> http://www.twinapex.com - Python professionals for hire
>
> --001485f85a508dc23a0472953231
> Content-Type: text/html; charset=ISO-8859-1
> Content-Transfer-Encoding: quoted-printable
>
> Hi,<br><br>DocFinderTab -1. DocFinderTab must be replaced by proper externa=
> l API documentation. The reason why DocFinderTab exist is that Plone commun=
> ity lacks proper practices to write and maintain code documentation.<br>
><br>When people come from other backgrounds (Java) and they are shown DocFi=
> nderTab and told this is your best and only hope to find Plone code documen=
> tation they will run screamingly away.<br><br>Run-time &quot;in-system&quot=
> ; doc generation is bad idea. Django tried it in some point for template ta=
> gs and it didn&#39;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.<br>
><br><div class=3D"gmail_quote">On Wed, Sep 2, 2009 at 12:23 PM, Alex Clark =
><span dir=3D"ltr">&lt;<a href=3D"mailto:[email protected]">[email protected]=
> t</a>&gt;</span> wrote:<br><blockquote class=3D"gmail_quote" style=3D"borde=
> r-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-le=
> ft: 1ex;">
> Heh, OK well I never got to it. And it seems we don&#39;t have a consensus,=
>  so I&#39;ll leave it.<br>
> But I would like to update it, so I&#39;ll take a look at Sphinx FWIW (yay,=
>  an excuse to look<br>
> at Sphinx!)<br></blockquote><div><br>We already have some Sphinx going on h=
> ere:<br><br><a href=3D"https://svn.plone.org/svn/collective/collective.deve=
> lopermanual/trunk/source/">https://svn.plone.org/svn/collective/collective.=
> developermanual/trunk/source/</a><br>
><br>I specifically disabled automatic API doc/module doc generation, becaus=
> e getting sane API doc output from Plone is little bit difficult.<br><br>I&=
> #39;d be interested to take a look how ZCML/Zope specific doc generators wo=
> rk. For example <a href=3D"http://apidoc.zope.org/++apidoc++/">http://apido=
> c.zope.org/++apidoc++/</a> generates documents for ZCML directives, though =
> it is obvious no one has never bothered to make useful docstrings for them.=
><br>
><br>I think we could have some kind of &quot;developer doc sprint&quot; int=
>  the upcoming conference to fix this problem once for all.<br><br>-Mikko<br=
>>=A0</div><div>--<br>Mikko Ohtamaa<br><a href=3D"http://www.twinapex.com">h=
> ttp://www.twinapex.com</a> - Python professionals for hire <br>
></div></div>
>
> --001485f85a508dc23a0472953231--
>
>
> --===============7515110798834770228==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> ------------------------------------------------------------------------------
> 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
> --===============7515110798834770228==
> Content-Type: text/plain; charset="us-ascii"
> MIME-Version: 1.0
> Content-Transfer-Encoding: 7bit
> Content-Disposition: inline
>
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs
>
> --===============7515110798834770228==--
>
>


-- 
Alex Clark · http://aclark.net
Buy Practical Plone 3: http://tinyurl.com/practical-plone


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