Ask Your Question
0

How to ensure examples in non-reference documentation test right

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

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

edit retag flag offensive close merge delete

1 answer

Sort by ยป oldest newest most voted
1

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

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.

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

edit flag offensive delete link more

Comments

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

Stats

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

Seen: 138 times

Last updated: Jul 05 '12