[Zope-dev] Proposal to add docs section to all top level zope3 package buildouts

[Paul Carduner]

On Mon, May 26, 2008 at 11:00 PM, Christian Theune <ct at 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