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.

> >
> > 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
Zope-Dev maillist  -  Zope-Dev@zope.org
**  No cross posts or HTML encoding!  **
(Related lists - 
 http://mail.zope.org/mailman/listinfo/zope )

Reply via email to