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

[Paul Carduner]

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).

Index: buildout.cfg
===================================================================
--- buildout.cfg	(revision 86938)
+++ buildout.cfg	(working copy)
@@ -1,6 +1,6 @@
 [buildout]
 develop = .
-parts = test py
+parts = test py docs
 find-links = http://download.zope.org/distribution/

 [test]
@@ -11,3 +11,8 @@
 recipe = zc.recipe.egg
 interpreter = py
 eggs = ${test:eggs}
+
+[docs]
+recipe = z3c.recipe.sphinxdoc
+eggs = z3c.recipe.sphinxdoc
+       zope.component [docs]
Index: src/zope/component/index.txt
===================================================================
--- src/zope/component/index.txt	(revision 0)
+++ src/zope/component/index.txt	(revision 0)
@@ -0,0 +1,24 @@
+Welcome to zope.component's documentation!
+==========================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   README
+   event
+   factory
+   persistentregistry
+   registry
+   socketexample
+   zcml
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

Property changes on: src/zope/component/index.txt
___________________________________________________________________
Name: svn:eol-style
   + native

Index: src/zope/component/zcml.txt
===================================================================
--- src/zope/component/zcml.txt	(revision 86938)
+++ src/zope/component/zcml.txt	(working copy)
@@ -912,6 +912,8 @@
 Protected utilities
 ~~~~~~~~~~~~~~~~~~~

+Not yet part of these tests::
+
     def testProtectedUtility(self):
         """Test that we can protect a utility.

Index: setup.py
===================================================================
--- setup.py	(revision 86938)
+++ setup.py	(working copy)
@@ -67,6 +67,7 @@
                 'zope.proxy',
                 'zope.i18nmessageid',
                 ],
+        docs = ['Sphinx'],
         test = ['zope.testing',
                 'ZODB3',
                 'zope.hookable',

-- 
Paul Carduner
http://www.carduner.net