Ask Your Question

How to ensure examples in non-reference documentation test right

asked 2012-07-05 17:04:00 -0600

kcrisman gravatar image

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)

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


    sage: f(x)

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/
     [2.7 s]

The temporary doctesting directory
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 flag offensive close merge delete

1 answer

Sort by ยป oldest newest most voted

answered 2012-07-05 19:08:33 -0600

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()

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

.. link


    sage: G = F.quadratic_twist(2); G
    Elliptic Curve defined by y^2 = x^3 - 4*x + 2 over Rational Field
    sage: G.conductor()
    sage: G.j_invariant()

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.

edit flag offensive delete link 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...

kcrisman gravatar imagekcrisman ( 2012-07-06 06:27:56 -0600 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools


Asked: 2012-07-05 17:04:00 -0600

Seen: 137 times

Last updated: Jul 05 '12