[Zope-dev] zc.zope3recipes : set offline tests everywhere

[Benji York]

On Mon, Aug 11, 2008 at 3:27 PM, Jim Fulton <jim at zope.com> wrote:
>
> On Aug 11, 2008, at 5:17 AM, Chris Withers wrote:
>
>> Christophe Combelles wrote:
>>> Is this change ok?
>>> It seems to solve the previous failures in the 3.4 kgs, and speeds
>>> up the test.
>>
>> I don't have a problem with the change, but this damages the
>> usefulness of README.txt as documentation.
>>
>> As someone who's never used zope3recipes, I'm going to read that and
>> wonder why offline = true is in there all the time as there are no
>> comments or explanation.
>>
>> Myself, I'd try and find another way of getting offline=true to
>> happen so that the docs can actually remain actual docs without test
>> cruft strewn throughout them.
>
>
> I agree.
>
> A sneaky way to do this would be to change the setup code to set a
> HOME environment variable to a temporary directory
> containing .buildout/default.cfg with:

I'll throw out another option: you can add doctest examples in reST
comments to enable offline mode.  Something like this:

"""
.. Set offline mode so the tests run correctly (or whatever).

    >>> DO THING HERE

Now we foo the bar with the baz

    >>> baz.foo(bar)
"""

When rendered to HTML (or any other target) the first part won't be
visible, but the second part will be.

If you have to do this much a global approach (like the one Jim
suggested) would likely be better, but I wanted to demonstrate this
approach because it can be useful when you don't want to pollute
otherwise good documentation.
-- 
Benji York
Senior Software Engineer
Zope Corporation