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

[Kent Tenney]

On Wed, Apr 23, 2008 at 2: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?

Sphinx provides added value to existing doc.
The PyPi page is fine, but it's nice to have a front page with
searching, indexing, TOC,
which is all basically free.

The page which exposes the doctests would explain the heritage of this material.
Some will prefer it to doc written from scratch.

The beauty of the existing doctest is that it is maintained and correct.
It would be nice if there could be a level of commit permission just for
enhancing the doctests for Sphinx.

see http://sphinx.pocoo.org/markup/index.html

>  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 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.
>
>  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?
>
>  Christophe
>
>
>  _______________________________________________
>  Zope-Dev maillist  -  Zope-Dev at zope.org
>  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 )
>