On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <optilude@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