On Wed, Apr 23, 2008 at 12:44 PM, Christophe Combelles <[EMAIL PROTECTED]>
> 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
> 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
> 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.
Zope-Dev maillist - Zope-Dev@zope.org
** No cross posts or HTML encoding! **
(Related lists -