On Mon, May 26, 2008 at 11:00 PM, Christian Theune <ct@gocept.com> wrote:
On Mon, May 26, 2008 at 02:14:12PM -0700, Paul Carduner wrote:
Short Version: - Need to add docs section to all top level zope 3 packages' buildout configs - Requires minor modification of packages - Please object if you don't want me to make changes.
Long Version: In my continued effort to make zope 3 documentation more accessible, I've come up with a buildout recipe that uses Sphinx to build documentation from the *.txt files of a package. I would like every package with documentation in it to start utilizing this buildout script. A few minor additions to each package's buildout.cfg and setup.py files are needed for the recipe to work. There also needs to be an index.txt file in the package's main source directory to serve as the "front page" for the generated documentation. I intend to make these changes to all top level zope3 packages which have documentation in them in the very near future unless someone objects. So if anyone objects to these changes, please voice your opinion now. To give you a better idea of the necessary changes, I've included a diff that makes the recipe work for zope.component. (note that the change to zcml.txt was needed for proper ReST syntax).
I think you change isn't necessary on this level. From the automation point of view, I would create a script that
- gathers all top level projects that are eggs - create a buildout.cfg on the fly - generate the documentation and upload it somewhere - rinse and repeat
Ok, since everyone seems to agree that a script like this is the way to go, I'll do that instead. I'll keep the buildout recipe around for those who want to generate documentation for just a single package. My hope was that if documentation played as front and center a role as unit tests do, then there would be more good documentation. But I guess if the community at large is not interested in this kind of overhead, then an automated script is the next best solution. I will however still have to go through all the .txt files and make sure they don't have any ReST errors. -- Paul Carduner http://www.carduner.net