Proposal to add docs section to all top level zope3 package buildouts
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
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 Christian -- Christian Theune · ct@gocept.com gocept gmbh & co. kg · forsterstraße 29 · 06112 halle (saale) · germany http://gocept.com · tel +49 345 1229889 7 · fax +49 345 1229889 1 Zope and Plone consulting and development
On Tue, May 27, 2008 at 2:00 AM, Christian Theune <ct@gocept.com> wrote:
I think you change isn't necessary on this level. From the automation point of view, I would create a script that [...]
+1 Any repo-wide change like this is expensive (and somewhat unlikely to stick), so a centralized approach (as Christian suggests) seems appropriate. -- Benji York Senior Software Engineer Zope Corporation
Benji York wrote:
On Tue, May 27, 2008 at 2:00 AM, Christian Theune <ct@gocept.com> wrote:
I think you change isn't necessary on this level. From the automation point of view, I would create a script that [...]
+1
Any repo-wide change like this is expensive (and somewhat unlikely to stick), so a centralized approach (as Christian suggests) seems appropriate.
+1 for that too. The script can also take care of uploading everything to a website somewhere. This is something that the individual approach can't do. That said, we may not want to upload the trunk docs to a website but the documentation of the last released egg or something. We could figure this out by cross-correlating SVN with PyPI... Regards, Martijn
Martijn Faassen wrote:
Benji York wrote:
On Tue, May 27, 2008 at 2:00 AM, Christian Theune <ct@gocept.com> wrote:
I think you change isn't necessary on this level. From the automation point of view, I would create a script that [...]
+1
Any repo-wide change like this is expensive (and somewhat unlikely to stick), so a centralized approach (as Christian suggests) seems appropriate.
+1 for that too. The script can also take care of uploading everything to a website somewhere. This is something that the individual approach can't do. That said, we may not want to upload the trunk docs to a website but the documentation of the last released egg or something. We could figure this out by cross-correlating SVN with PyPI...
... or the KGS (which is available from our SVN in a machine-readable form, i.e. ConfigParser)
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
On Tue, May 27, 2008 at 11:36 AM, Paul Carduner <paulcarduner@gmail.com> wrote:
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.
Hopefully the documentation you're generating will be so overwhelmingly loved that we'll begin incorporating support for it at the project level. Until then the less-invasive approach is warranted. -- Benji York Senior Software Engineer Zope Corporation
participants (5)
-
Benji York -
Christian Theune -
Martijn Faassen -
Paul Carduner -
Philipp von Weitershausen