# How to ensure examples in non-reference documentation test right

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 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.

edit retag close merge delete

Sort by » oldest newest most voted

In rst files, you need to link different code blocks together, if you want them to be treated as a single block (e.g., if you want variables, etc., defined in one block to still be defined in the second one). For example, from tour_advanced.rst in the tutorial:

::

sage: F = EllipticCurve_from_j(110592/37)
sage: F.conductor()
37

However, the twist of :math:F by 2 gives an isomorphic curve.

::

Elliptic Curve defined by y^2 = x^3 - 4*x + 2 over Rational Field
sage: G.conductor()
2368
sage: G.j_invariant()
110592/37


Alternatively, you can put .. linkall at the top of the file, and then all code blocks in the file will be linked. See the developer's guide.

more

That is awesome! I didn't even bother reading the devel guide for this (my loss) because I figured there was no way anyone had taken on the task of documenting this...

( 2012-07-06 06:27:56 -0600 )edit