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

[Marius Gedminas]

On Wed, Apr 23, 2008 at 09:44:45PM +0200, Christophe Combelles 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 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.

+1 for strict separation of API docs from tests.

> 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?

Marius Gedminas
-- 
* philiKON wonders what niemeyer is committing :)
*** benji_york is now known as benji
<benji> murder?
		-- #zope3-dev
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://mail.zope.org/pipermail/zope-dev/attachments/20080423/789c0a7f/attachment.bin