local/bin/sage-doctest
implements
documentation testing in Sage (see Chapter 4.3 for more
details). When writing documentation, keep the following points in
mind:
2/3
is replaced by ZZ(2)/ZZ(3)
, which evaluates to
2/3
as a rational instead of the Python int 0
. For
more information on preparsing see Section 3.1.
random
it is executed by
sage-doctest
but sage-doctest
does not check that the
output agrees with the output in the documentation string.
long time
then that line is
not tested unless the -
long option is given, e.g.,
sage -t -long f.py
. Use this to include examples that take more
than about a second to run; these will not be run regularly during
Sage development, but will get run before major releases. No
example should take more than about 30 seconds.
Here is the Lseries
function docstring which contains the phrase
long time
and is taken from
SAGE_ROOT/devel/sage/sage/schemes/elliptic_curves/ell_rational.py
def Lseries(self, s): r""" Returns the value of the L-series of the elliptic curve E at s, where s must be a real number. Use self.Lseries_extended for s complex. \note{If the conductor of the curve is large, say $>10^{12}$, then this function will take a very long time, since it uses an $O(\sqrt{N})$ algorithm.} EXAMPLES: sage: E = EllipticCurve([1,2,3,4,5]) sage: E.Lseries(1) 0.000000000000000 sage: E.Lseries('1.1') # long time (!) 0.28549100767814833
todo: not implemented
, it is never
tested. It is good to include lines like this to make clear
what we want Sage to eventually implement:
sage: factor(x*y - x*z) # todo: not implemented
optional
it is not
tested unless the -
optional flag is passed, e.g.,
sage -t -optional f.py
. (Note that -optional
must not be the first argument to sage
.) Use this
to include doctests that require optional packages.
For example,
sage: E.padic_regulator(5) # requires optional MAGMA package xxx
optional
, package
, and installed
, then
the entire documentation string is not executed unless the
-optional
flag is passed to sage -t
. This is useful
for a long sequence of examples that all require that an optional
package be installed.
Using sage_search
from the Sage prompt or grep
one can
easily find aforementioned keywords and in the case of todo: not
implemented
use the results to motivate further development on Sage.
See About this document... for information on suggesting changes.