On Wed, Apr 23, 2008 at 12:44 PM, Christophe Combelles <[EMAIL PROTECTED]> 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 _______________________________________________ Zope-Dev maillist - Zope-Dev@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 )