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

[Martin Aspeli]

Hi Paul,

> I guess I have officially volunteered to write content for the new
> zope.org site in the zope 3 section.  Part of that involves describing
> what zope 3 is in a concise manner.  I realize there are probably a
> lot of different opinions about what zope 3 is, so I would like to
> solicit the community to provide me with some ideas of what zope 3 is
> to you.  It doesn't have to be anything fancy or publishable, just a
> bulleted list of "what zope 3 means to me" would be fine.  I will
> aggregate these ideas and try to present it in an easy to read form.
> I don't want to start any arguments about what zope 3, so let's wait
> until I have something written before we start arguing :).

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.

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

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

>  To this end I have taken a look at sphinx, the new documentation
> publishing tool used by python.org.  In short, it looks really good,
> and I think we could use it for zope documentation.  Here is my
> thinking:

Cool!

> Keeping *lots* of documentation maintained in any CMS or wiki style
> website is hard, because the people writing the code want to maintain
> everything (including documentation) in one place: subversion.  It is
> too much to ask every developer to update a website every time they
> make a change to the codebase, because the website lives in firefox,
> while the code lives in vim or emacs.  But if the documentation lives
> with the code, updating the documentation can become part of the
> normal flow of writing software (just like writing tests is part of
> the normal flow).  So ideally, all package specific documentation
> *including tutorials and other end user docs* should live along side
> the code in subversion.  Now the trick is just publishing this
> documentation.

I agree with this assessment.

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

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

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

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

Martin

-- 
Author of `Professional Plone Development`, a book for developers who
want to work with Plone. See http://martinaspeli.net/plone-book