[Zope-dev] patterns for using sphinx with the Zope Toolkit?

[Chris McDonough]

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