On Wed, Apr 23, 2008 at 12:01 PM, Martin Aspeli <[EMAIL PROTECTED]> 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 _______________________________________________ Zope-Dev maillist - [email protected] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
