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

[Paul Carduner]

Hi All,

<lots of small talk follows, scroll down to **** section for the main
point of this email>

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

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

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.

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

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.

What do people think of this idea and who wants to help me implement
it this weekend?

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