Ticket #13899: 13899_doctest.patch

File 13899_doctest.patch, 4.5 KB (added by jdemeyer, 7 years ago)
  • doc/en/developer/conventions.rst

    # HG changeset patch
    # User Jeroen Demeyer <jdemeyer@cage.ugent.be>
    # Date 1357226522 -3600
    # Node ID 2d010e7d5870c69385b87f2bce40fdfd5be9b40e
    # Parent  f50ccddbc81a2b6b77ab684b68f5a0e9fa3e3e5e
    Fix broken doctests, mention known bug #12815
    
    diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
    a b  
    662662            """
    663663            See ``HillCryptosystem`` for full documentation.
    664664
    665         EXAMPLES::
    666         ...
    667         """
     665            EXAMPLES::
     666
     667                ...
     668            """
    668669
    669670    Note also that the first docstring is printed if users type
    670671    "HillCryptosystem?" at the "sage:" prompt.
     
    685686The file ``f.py`` is not imported when running tests unless you have
    686687arranged that it be imported into your Sage environment, i.e. unless
    687688its functions are available when you start Sage using the ``sage``
    688 command. For example, the function ``cdd_convert`` in the file
    689 ``SAGE_ROOT/devel/sage/sage/geometry/polyhedra.py`` includes
    690 an EXAMPLES block containing the following:
     689command. For example, the function ``AA()`` in the file
     690``SAGE_ROOT/devel/sage/sage/algebras/steenrod/steenrod_algebra.py``
     691includes an EXAMPLES block containing the following:
    691692
    692693::
    693694
    694         sage: from sage.geometry.polyhedra import cdd_convert
    695         sage: cdd_convert(' 1 1 0 0')
    696         [1, 1, 0, 0]
     695    sage: from sage.algebras.steenrod.steenrod_algebra import AA as A
     696    sage: A()
     697    mod 2 Steenrod algebra, milnor basis
    697698
    698 Sage does not know about the function ``cdd_convert`` by default, so
     699Sage does not know about the function ``AA()`` by default, so
    699700it needs to be imported before it is tested. Hence the first line in
    700701the example.
    701702
     
    715716   ``2/3`` as a rational instead of the Python int ``0``. For more
    716717   information on preparsing, see :ref:`section-preparsing`.
    717718
    718 -  If a test outputs to a file, the file should be in a temporary
    719    directory.  For example (taken from the file
    720    ``SAGE_ROOT/devel/sage/sage/plot/plot.py``)::
     719-  If a test outputs to a file, the file should be a temporary file.
     720   Use :func:`tmp_filename` to get a temporary filename,
     721   or :func:`tmp_dir` to get a temporary directory.
     722   For example (taken from the file
     723   ``SAGE_ROOT/devel/sage/sage/plot/graphics.py``)::
    721724
    722         sage: fig.savefig(os.path.join(SAGE_TMP, 'test.png'))
    723 
    724    Here ``fig.savefig`` is the function doing the saving, ``SAGE_TMP``
    725    is a temporary directory---this variable will always be defined
    726    properly during automated testing---and ``os.path.join`` is the
    727    preferred way to construct a path from a directory and a file. It
    728    works more generally than a Unix-flavored construction like
    729    ``SAGE_TMP + '/test.png'``.  If you want to use ``SAGE_TMP`` in
    730    Sage code, not just in a doctest, then you need to import
    731    it. Search the Sage code for examples.
     725       sage: plot(x^2 - 5, (x, 0, 5), ymin=0).save(tmp_filename(ext='.png'))
    732726
    733727-  If a test line contains the text ``random``, it is executed by
    734728   ``sage-doctest`` but ``sage-doctest`` does not check that the
     
    797791
    798792       sage: A = matrix(RDF, 8, range(64))
    799793       sage: U, S, V = A.SVD()
    800        sage: (U.transpose()*U-identity_matrix(8)).norm()    # abs tol 1e-10
     794       sage: (U.transpose()*U-identity_matrix(8)).norm(p=2)    # abs tol 1e-10
    801795       0.0
    802796       
    803797   The 8-th cyclotomic field is generated by the complex number
     
    812806   
    813807   ::
    814808       
    815        sage: K = CyclotomicField(8)                     
    816        sage: g = K.gen(0); g
    817        zeta8
     809       sage: K.<zeta8> = CyclotomicField(8)
    818810       sage: N(zeta8)                             # absolute tolerance 1e-15
    819811       0.707106781186548 + 0.707106781186547*I
    820812
     
    822814   the root should normally print as ``1e+16``, or something similar.
    823815   However, the tolerance testing causes the doctest framework to
    824816   use the output in a *computation*, so any valid text representation
    825    of the predicted value may be used.
     817   of the predicted value may be used. **This is actually broken**, see
     818   :trac:`12815`.
    826819   
    827820   ::
    828821
    829822       sage: y = polygen(RDF, 'y')
    830        sage: p = (y - 10^16)*(y-10^(-13))*(y-2); p
    831        y^3 + (-1e+16)*y^2 + (2e+16)*y - 2000.0
     823       sage: p = (y - 10^16) * (y - 10^-13) * (y - 2)
    832824       sage: p.roots(multiplicities=False)[2]     # relative tol 1e-10
    833        10^16
     825       1e16
    834826
    835827-  If a line contains ``todo: not implemented``, it is never
    836828   tested. It is good to include lines like this to make clear what we