[Zope-dev] Re: new zope.org, sphinx, and documentation management

[Paul Carduner]

On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <optilude at gmx.net> wrote:
> Hi Paul,
>
>  I've tried to sum up my understanding of how Zope 3 fits in with the Zope
> universe here:
>
>  http://zode01.lovelysystems.com/projects
>
>  Beyond that, I think Zope 3 is becoming more and more a collection of
> libraries and less of an application server.
>

Ok, I will add that to my list of bullets as something that someone
out there thinks of zope.  Thanks!

> > Besides giving the 10000 foot view of zope 3, there is also a section
> > for zope 3 documentation on the new site, which should probably
> > include detailed developer documentation along with tutorials, howtos,
> > references, etc.  Fortunately, a little known fact is that there is
> > already a fair amount of up-to-date documentation about many zope3
> > packages in the form of doctests (some better written for end-user
> > consumption than others).
> >
>
>  I think this is true, but doctests are only useful if you know where to
> look and you have the required background.
>
>  I would argue that we need more "prose-style" introduction/background
> documentation. We probably also need a human-edited overview of the most
> important Zope 3 packages. We can then point to doctests for more detailed
> stuff.
>

I agree.  Prose are good, with the one caveat that the new user coming
to check out/download/install/play with zope (3) for 30 minutes, might
not care to read a long story about the history of zope.  I think such
a history is important, but not as high a priority than just providing
the information necessary to utilize the framework.  Plus, I think
it's possible that some of that prose-style instroduction/background
could live with the code (not as a doctest, but just as a doc).

> > Few people know about this because the
> > documentation is not aggregated anywhere (except for some bits on
> > apidoc.zope.org).  You have to know to look on svn.zope.org or pypi
> > pages to find the rest of it.  Rather than writing a bunch of new
> > documentation on the new zope.org site from scratch, I would like to
> > harness the existing documentation, and just publish it in a nice way.
> >
>
>  Yep!
>
>  Please note that we can enable the reST parser in Plone so that we can
> paste reST into a document and have it render somewhat-nicely. That still
> presumes some manual work though.
>

Big +1.  I much prefer working on a reST document in emacs and copying
and pasting into the plone site when I'm ready.  That also allows me
to save a nicely formatted local copy easily.  Good for train rides
with no internet.


> > ***** THE POINT OF THIS EMAIL IS BELOW *****
> >
> > I would like to develop a buildout recipe that generates aggregated
> > documentation for a package (like z3c.form) using sphynx and publishes
> > it to the new zope.org website.  I want updating of zope documentation
> > on zope.org to be as easy as uploading a package to pypi:
> >
>
>  Nice. :)
>
>  I wonder if perhaps it would be easier to start with, to create a static
> HTML site out of this documentation. If zope.org (as per
> http://zode01.lovelysystems.com) is the "shop window" to Zope, then we can
> focus on telling a compelling story there. We can have links to, say,
> doc.zope.org (much like python.org does with doc.python.org), which can be
> static HTML that's generated by this stuff.
>

Yep, my first goal is to learn more about sphinx and see what it can
do.  I'll probably be generating docs and sticking them on
http://docs.carduner.net for the time being.

> > When you are ready to make a release of a package, you would then do:
> >  $ cd z3c.form/tags/2.0/
> >  $ python setup.py register sdist upload
> >  $ ./bin/buildout
> >  $ ./bin/update-documentation
> >
> > You would then be able to go to
> > http://www.zope.org/projects/zope3/documentation/z3c.form and see
> > everything from developer docs, to tutorials, to how-tos, etc.
> >
>
>  We could also write some code that pushes this into Plone over XML-RPC or
> HTTP requests (or even zope.testbrowser...).

This idea I like.  That sounds like the way to do it.

>  Or: we could write some kind of Plone content type, parameterised with an
> svn url, that pulled straight from svn and rendered doctests inline (this
> means we wouldn't need a buildout recipe or sphinx, though we would need
> some in-Plone caching and it'd be a bit of work to set up all the packages).

This is probably overkill.

> > What do people think of this idea and who wants to help me implement
> > it this weekend?
> >
>
>  I would start with the simple HTML approach, personally. It may be all we
> need.

Hopefully there will be a first sample of this in the next hour or so.

Thanks for your response!

-- 
Paul Carduner
http://www.carduner.net