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:


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.


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


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

I agree with this assessment.


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.


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

Zope-Dev maillist  -  Zope-Dev@zope.org
**  No cross posts or HTML encoding!  **
(Related lists - http://mail.zope.org/mailman/listinfo/zope-announce
http://mail.zope.org/mailman/listinfo/zope )

Reply via email to