[Zope-dev] docs.zope.org automation

[Jens Vagelpohl]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi everyone,

Here's a followup on a docs.zope.org automation task I took over during
one of the Zope developer IRC metings[1]. The task was to provide
individual package documentation, if it exists, directly underneath
docs.zope.org, e.g.:

http://docs.zope.org/zope.event/

... and keep those docs updated from the current trunk documentation.

I expanded that task a little bit by generating content that shows the
list of packages divided by project and makes it obvious which packages
have documentation and which don't. All of that is in a buildout that
automatically generates the docs.zope.org website and does away with the
single static HTML page with the "dead" new new new new.zope.org design
and uses stock Sphinx design.

If you visit docs.zope.org now you'll notice that the content on the
main page has not changed much, it's just been updated and re-ordered
slightly. What's new are those links I prefixed with "Package
documentation", those point to the autogenerated index pages for each
project. As noted on top of most of these index pages, if a package is
listed but not linked it doesn't have documentation the scripts can
recognize.

Currently the buildout can recognize the standard Sphinx documentation
layout with a folder named "doc" or "docs" in the package root and a
Sphinx configuration and content therein. The buildout can also use a
kludge and pull in content that is documented using
"z3c.recipe.sphinxdoc" maintained in a separate buildout, but I'm hoping
those project authors would consider using the standard layout as
exemplified by e.g. zope.event[2] and championed by e.g. Tres, Christian
Theune, and several others (including me).

There's a README in the buildout that explains how to do specific
tasks[3]. If you have any questions let me know.

jens


[1] http://docs.zope.org/zopetoolkit/zope-dev/zope-dev-20100727.html
[2] http://svn.zope.org/zope.event/trunk/docs/
[3] http://svn.zope.org/docs.zope.org_website/
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.8 (Darwin)

iEYEARECAAYFAkxUW7gACgkQRAx5nvEhZLLhAgCgsHQeyHi9/xDc9aYvLELlM1/e
Z0sAnirP2CO3zQ/MTntWTixDj7MIStgA
=gadb
-----END PGP SIGNATURE-----