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

[Paul Carduner]

On Wed, Apr 23, 2008 at 12:44 PM, Christophe Combelles <ccomb at free.fr> wrote:
> Paul Carduner a écrit :
>
>
> > ***** 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.
> >
> >
>
>  Won't it be redundant with the doctests displayed on the PyPI?
>  You speak about things like z3c.form, i.e. individual packages. They
> already
>  have their doc (readme) displayed on the cheeseshop, which is the first
> place to look for packages.

The problem is that the cheeseshop produces one page for *all* the
documentation you upload to it.  This is really not ideal for more
than a simple introduction.  The zopeproject page (or the zcontact
page) on pypi are good examples where pypi is a nice starting point.
But for more extensive documentation, pypi just isn't going to cut it.
 It would be interesting if sphinx were one day integrated into pypi,
but I doubt that will happen in the near future.

> The problem is that many README.txt are more
> unittests than high level docs. In my opinion many README.txt contents
> should be moved into deeper functional doctests, and replaced by real
> introductions, or easy-to-read howtos.

I agree.  Part of the work involved in utilizing doctests for
documentation would be editing the existing doctests themselves to
make them more readable and end user consumable, and refactoring
low-level doctests to deeper levels that are more test than doc, and
not having them appear as part of the greater documentation at all.

>  On zope.org, instead of individual egg docs, we need high level docs or
>  integration docs that cover several packages at once. In which eggs do you
> want
>  to put them?

I would argue that integration docs should be in the form of a
tutorial or demo.  Take for example z3c.formdemo.  This integrates
quite a number of different packages and would be a great place for
"integration documentation".  Basically, integration docs would have
their own package in svn.zope.org, in the form of an executable demo
plus lots of great documentation.

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