Ticket #13899: trac_13899-doctest-rebase.patch

File trac_13899-doctest-rebase.patch, 4.2 KB (added by kcrisman, 7 years ago)
  • doc/en/developer/conventions.rst

    # HG changeset patch
    # User Jeroen Demeyer <jdemeyer@cage.ugent.be>
    # Date 1357226522 -3600
    # Node ID e3505549ffa6387983bdb4032ee21f6cfa4ff8cb
    # Parent  dae73a4694cbe91a3b3219ea0a4da05d63073707
    Fix broken doctests, mention known bug #12815
    
    diff --git a/doc/en/developer/conventions.rst b/doc/en/developer/conventions.rst
    a b  
    687687The file ``f.py`` is not imported when running tests unless you have
    688688arranged that it be imported into your Sage environment, i.e. unless
    689689its functions are available when you start Sage using the ``sage``
    690 command. For example, the function ``cdd_convert`` in the file
    691 ``SAGE_ROOT/devel/sage/sage/geometry/polyhedra.py`` includes
    692 an EXAMPLES block containing the following:
     690command. For example, the function ``AA()`` in the file
     691``SAGE_ROOT/devel/sage/sage/algebras/steenrod/steenrod_algebra.py``
     692includes an EXAMPLES block containing the following:
    693693
    694694::
    695695
    696         sage: from sage.geometry.polyhedra import cdd_convert
    697         sage: cdd_convert(' 1 1 0 0')
    698         [1, 1, 0, 0]
     696    sage: from sage.algebras.steenrod.steenrod_algebra import AA as A
     697    sage: A()
     698    mod 2 Steenrod algebra, milnor basis
    699699
    700 Sage does not know about the function ``cdd_convert`` by default, so
     700Sage does not know about the function ``AA()`` by default, so
    701701it needs to be imported before it is tested. Hence the first line in
    702702the example.
    703703
     
    717717   ``2/3`` as a rational instead of the Python int ``0``. For more
    718718   information on preparsing, see :ref:`section-preparsing`.
    719719
    720 -  If a test outputs to a file, the file should be in a temporary
    721    directory.  For example (taken from the file
    722    ``SAGE_ROOT/devel/sage/sage/plot/plot.py``)::
     720-  If a test outputs to a file, the file should be a temporary file.
     721   Use :func:`tmp_filename` to get a temporary filename,
     722   or :func:`tmp_dir` to get a temporary directory.
     723   For example (taken from the file
     724   ``SAGE_ROOT/devel/sage/sage/plot/graphics.py``)::
    723725
    724         sage: fig.savefig(os.path.join(SAGE_TMP, 'test.png'))
    725 
    726    Here ``fig.savefig`` is the function doing the saving, ``SAGE_TMP``
    727    is a temporary directory---this variable will always be defined
    728    properly during automated testing---and ``os.path.join`` is the
    729    preferred way to construct a path from a directory and a file. It
    730    works more generally than a Unix-flavored construction like
    731    ``SAGE_TMP + '/test.png'``.  If you want to use ``SAGE_TMP`` in
    732    Sage code, not just in a doctest, then you need to import
    733    it. Search the Sage code for examples.
     726       sage: plot(x^2 - 5, (x, 0, 5), ymin=0).save(tmp_filename(ext='.png'))
    734727
    735728-  If a test line contains the text ``random``, it is executed by
    736729   ``sage-doctest`` but ``sage-doctest`` does not check that the
     
    799792
    800793       sage: A = matrix(RDF, 8, range(64))
    801794       sage: U, S, V = A.SVD()
    802        sage: (U.transpose()*U-identity_matrix(8)).norm()    # abs tol 1e-10
     795       sage: (U.transpose()*U-identity_matrix(8)).norm(p=2)    # abs tol 1e-10
    803796       0.0
    804797       
    805798   The 8-th cyclotomic field is generated by the complex number
     
    814807   
    815808   ::
    816809       
    817        sage: K = CyclotomicField(8)                     
    818        sage: g = K.gen(0); g
    819        zeta8
     810       sage: K.<zeta8> = CyclotomicField(8)
    820811       sage: N(zeta8)                             # absolute tolerance 1e-15
    821812       0.707106781186548 + 0.707106781186547*I
    822813
     
    824815   the root should normally print as ``1e+16``, or something similar.
    825816   However, the tolerance testing causes the doctest framework to
    826817   use the output in a *computation*, so any valid text representation
    827    of the predicted value may be used.
     818   of the predicted value may be used. **This is actually broken**, see
     819   :trac:`12815`.
    828820   
    829821   ::
    830822
    831823       sage: y = polygen(RDF, 'y')
    832        sage: p = (y - 10^16)*(y-10^(-13))*(y-2); p
    833        y^3 + (-1e+16)*y^2 + (2e+16)*y - 2000.0
     824       sage: p = (y - 10^16) * (y - 10^-13) * (y - 2)
    834825       sage: p.roots(multiplicities=False)[2]     # relative tol 1e-10
    835        10^16
     826       1e16
    836827
    837828-  If a line contains ``todo: not implemented``, it is never
    838829   tested. It is good to include lines like this to make clear what we