How to ensure examples in non-reference documentation test right

edit

Consider the following rst file, called Tiny.rst, and placed somewhere in the Sage doc tree where I know that things work properly.

.. -*- coding: utf-8 -*-


Tiny Test File
==============

A command
---------

Here's an example.

::

    sage: factor(2012)
    2^2 * 503


Functions in Sage
-----------------

Let's do some functions.

::

    sage: f(x)=x^2
    sage: f(x)
    x^2

Let's ask Sage what the function is one more time.

::

    sage: f(x)
    x^2

When I test it, regular commands and commands together test fine. But commands with user-defined things that are in another literal block don't.

sage -t  devel/sage-main/doc/en/.../Tiny.rst
**********************************************************************
File "/Users/.../sage-5.1.beta5/devel/sage-main/doc/en/.../Tiny.rst", line 51:
    sage: f(x)
Exception raised:
      File "<doctest __main__.example_3[2]>", line 1, in <module>
        f(x)###line 51:
    sage: f(x)
    NameError: name 'f' is not defined
**********************************************************************
1 items had failures:
   1 of   4 in __main__.example_3
***Test Failed*** 1 failures.
For whitespace errors, see the file /Users/.../.sage/tmp/new_host_2.home-49485/Tiny_49488.py
     [2.7 s]

----------------------------------------------------------------------
The temporary doctesting directory
   /Users/.../.sage/tmp/new_host_2.home-49485
was not removed: it is not empty, presumably because doctests
failed or doctesting was interrupted.

----------------------------------------------------------------------

The following tests failed:

    sage -t  devel/sage-main/doc/en/.../Tiny.rst # 1 doctests failed
----------------------------------------------------------------------
Timings have been updated.

If you remove the words before the second f(x), the same thing happens.

So what gives? Clearly a lot of the documentation doesn't have this issue.