On Wed, Apr 23, 2008 at 12:44 PM, Christophe Combelles <ccomb@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