Re: [Zope-dev] patterns for using sphinx with the Zope Toolkit?
Martijn Faassen wrote: > Hi there, > > I am interested in creating sphinx-driven documentation for Zope Toolkit > packages. I'd like to maintain the documentation for a package (say, > zope.component) in that package, in a 'doc' directory. > > I'm wondering what experiences people have with maintaining Sphinx docs. > I've used plain Sphinx before, but are there any buildout recipes people > recommend, for instance? > > It'd also be interesting to explore using Manuel - how would one add > manuel-based testing to a Sphinx documentation tree? I'd like to give > the priority to testing documentation samples as opposed to > doctest-driven testing. I also want to be careful: sometimes the doctest > setup fluff tends to distract from clear documentation, and sometimes > the effort in composing doctests will slow down writing documentation. > I'd therefore want manuel-tested sample code to be incremental. I want > to be able to start out with purely untested sample code and then > gradually convert *some* samples over to Manuel. How could we support > that pattern? We've had good success with http://pypi.python.org/pypi/collective.recipe.sphinxbuilder And also http://pypi.python.org/pypi/repoze.sphinx.autointerface for interface docs > Ideas and opinions? This will also help me write the "writing Zope > Toolkit documentation" document. :) Yay :) Martin -- Author of `Professional Plone Development`, a book for developers who want to work with Plone. See http://martinaspeli.net/plone-book ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
Re: [Zope-dev] patterns for using sphinx with the Zope Toolkit?
Martijn Faassen wrote: > Hi there, > > I am interested in creating sphinx-driven documentation for Zope Toolkit > packages. I'd like to maintain the documentation for a package (say, > zope.component) in that package, in a 'doc' directory. > > I'm wondering what experiences people have with maintaining Sphinx docs. > I've used plain Sphinx before, but are there any buildout recipes people > recommend, for instance? I just use it out of the box after generating some files using "sphinx-quickstart". I suspect just changing the resulting Makefile alias from: SPHINXBUILD = sphinx-build To: SPHINXBUILD = ../../../bin/sphinx-build .. or so, for some buildout usage would work just fine. > It'd also be interesting to explore using Manuel - how would one add > manuel-based testing to a Sphinx documentation tree? I'd like to give > the priority to testing documentation samples as opposed to > doctest-driven testing. I also want to be careful: sometimes the doctest > setup fluff tends to distract from clear documentation, and sometimes > the effort in composing doctests will slow down writing documentation. > I'd therefore want manuel-tested sample code to be incremental. I want > to be able to start out with purely untested sample code and then > gradually convert *some* samples over to Manuel. How could we support > that pattern? Python samples in Sphinx docs are generated like so: .. code-block:: python a == 1 I did a bit of fooling around with Manuel, because I wanted to make sure that the code blocks in my documentation actually worked, but I wound up in a place where I use Manuel to check only the *syntax* of a subets of the Sphinx code blocks I use. It will do this right out of the box if you read the Manuel docs But I couldn't really figure out a way to do the moral equivalent of this: .. code-block:: python a == 1 .. manuel-expect: True Maybe I missed it. But even so, having Manuel to check even the syntax of code blocks is really useful; I found a couple of errors. > Ideas and opinions? This will also help me write the "writing Zope > Toolkit documentation" document. :) - C ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
[Zope-dev] patterns for using sphinx with the Zope Toolkit?
Hi there, I am interested in creating sphinx-driven documentation for Zope Toolkit packages. I'd like to maintain the documentation for a package (say, zope.component) in that package, in a 'doc' directory. I'm wondering what experiences people have with maintaining Sphinx docs. I've used plain Sphinx before, but are there any buildout recipes people recommend, for instance? It'd also be interesting to explore using Manuel - how would one add manuel-based testing to a Sphinx documentation tree? I'd like to give the priority to testing documentation samples as opposed to doctest-driven testing. I also want to be careful: sometimes the doctest setup fluff tends to distract from clear documentation, and sometimes the effort in composing doctests will slow down writing documentation. I'd therefore want manuel-tested sample code to be incremental. I want to be able to start out with purely untested sample code and then gradually convert *some* samples over to Manuel. How could we support that pattern? Ideas and opinions? This will also help me write the "writing Zope Toolkit documentation" document. :) Regards, Martijn ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
[Zope-dev] Zope Tests: 6 OK
Summary of messages to the zope-tests list. Period Fri Jan 1 12:00:00 2010 UTC to Sat Jan 2 12:00:00 2010 UTC. There were 6 messages: 6 from Zope Tests. Tests passed OK --- Subject: OK : Zope-2.10 Python-2.4.6 : Linux From: Zope Tests Date: Fri Jan 1 20:37:05 EST 2010 URL: http://mail.zope.org/pipermail/zope-tests/2010-January/013305.html Subject: OK : Zope-2.11 Python-2.4.6 : Linux From: Zope Tests Date: Fri Jan 1 20:39:05 EST 2010 URL: http://mail.zope.org/pipermail/zope-tests/2010-January/013306.html Subject: OK : Zope-2.12 Python-2.6.4 : Linux From: Zope Tests Date: Fri Jan 1 20:41:06 EST 2010 URL: http://mail.zope.org/pipermail/zope-tests/2010-January/013307.html Subject: OK : Zope-2.12-alltests Python-2.6.4 : Linux From: Zope Tests Date: Fri Jan 1 20:43:06 EST 2010 URL: http://mail.zope.org/pipermail/zope-tests/2010-January/013308.html Subject: OK : Zope-trunk Python-2.6.4 : Linux From: Zope Tests Date: Fri Jan 1 20:45:06 EST 2010 URL: http://mail.zope.org/pipermail/zope-tests/2010-January/013309.html Subject: OK : Zope-trunk-alltests Python-2.6.4 : Linux From: Zope Tests Date: Fri Jan 1 20:47:06 EST 2010 URL: http://mail.zope.org/pipermail/zope-tests/2010-January/013310.html ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )
[Zope-dev] broken zope.publisher because of new content types in zope.contenttype
Hi all Since aaron added new mimetypes e.g. application/javascript, the _implicitResult method in zope.publisher.http.py (line 794) is broken because the method checks for text/* content types if unicode is given: def _implicitResult(self, body): encoding = getCharsetUsingRequest(self._request) or 'utf-8' content_type = self.getHeader('content-type') if isinstance(body, unicode): try: if not content_type.startswith('text/'): raise ValueError( 'Unicode results must have a text content type.') except AttributeError: raise ValueError( 'Unicode results must have a text content type.') Sould we remove this basic content type check above? Or enhance the check with the new added unicode valid content types like application/javascript. btw, the RFC is just Informational which defines this changes. See: http://www.rfc-editor.org/rfc/rfc4329.txt Regards Roger Ineichen _ END OF MESSAGE ___ Zope-Dev maillist - Zope-Dev@zope.org https://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - https://mail.zope.org/mailman/listinfo/zope-announce https://mail.zope.org/mailman/listinfo/zope )