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

[Lennart Regebro]

On Mon, Jan 4, 2010 at 00:43, Chris McDonough <chrism at plope.com> wrote:
> Yeah.  I haven't thought about this much, so it might be bollocks, but I
> think something like this is what I'm after:
>
> .. code-block-setup::
>
...
>
> .. code-block:: python
>   :linenos:
>
....
>
> .. code-block-teardown::
>   del sys.modules['models']
>

You don't actually have a test in that example.

Here is my usecases:

Numero Uno1
========

Here I call a method that will print things to the stdout. I need to
make sure that it prints the correct thing, but I do not want that
thing to be shown in the document.

.. testsetup::

    import sys
    sys.argv = ['setup.py', 'build']

.. testcode::

    from setuptools import setup, find_packages

    setup(name='Porting to Python 3 examples',
          version=1.0,
    )

.. testoutput::
    :hide:

    running build
    ...
    writing manifest file 'Porting_to_Python_3_examples.egg-info/SOURCES.txt'

Numero Due
========

Here I call a method that will raise an error. I need to make sure
that it raises the correct thing, but I do not want that thing to be
shown in the document.

.. testsetup::

    import sys
    sys.argv = ['setup.py', 'build']

.. testcode::

    from setuptools import setup, find_packages

    setup(name='Porting to Python 3 examples',
          version=1.0,
    )

.. testoutput::
    :hide:

    Traceback (most recent call last):
    SystemExit: False

Trinity
=====

Here I need a from __future__ import, but I want to use the >>>
format, because I *do* want to show the result.

.. doctest::

    >>> from __future__ import division
    >>> 5/2
    2.5

It is of no great importance what the blocks are called, as long as
Sphinx recognizes them as code blocks and indents them the same (I
don't know Sphinx rules there). I do prefer having a separate "setup"
and "teardown" (although I don't use that one currently) before just
using invisible code blocks as I find it clearer, even though I
realize it's just different names for the same thing, really.

I'll not that none of the above works with Manuels latest release. Uno
et Due works with trunk because I added Sphinx support yesterday
(which should have been added to a branch, but I guess I got a
temporary attack of Plone Collective disease), and Trinity I have
working because I made a custom extension to Manuel where I override
the standard doctest support and use a parser that is hacked to
special case __future__ imports.

-- 
Lennart Regebro: Python, Zope, Plone, Grok
http://regebro.wordpress.com/
+33 661 58 14 64