# 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


687  687  The file ``f.py`` is not imported when running tests unless you have 
688  688  arranged that it be imported into your Sage environment, i.e. unless 
689  689  its 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: 
 690  command. For example, the function ``AA()`` in the file 
 691  ``SAGE_ROOT/devel/sage/sage/algebras/steenrod/steenrod_algebra.py`` 
 692  includes an EXAMPLES block containing the following: 
693  693  
694  694  :: 
695  695  
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 
699  699  
700   Sage does not know about the function ``cdd_convert`` by default, so 
 700  Sage does not know about the function ``AA()`` by default, so 
701  701  it needs to be imported before it is tested. Hence the first line in 
702  702  the example. 
703  703  
… 
… 

717  717  ``2/3`` as a rational instead of the Python int ``0``. For more 
718  718  information on preparsing, see :ref:`sectionpreparsing`. 
719  719  
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``):: 
723  725  
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 directorythis variable will always be defined 
728   properly during automated testingand ``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 Unixflavored 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')) 
734  727  
735  728   If a test line contains the text ``random``, it is executed by 
736  729  ``sagedoctest`` but ``sagedoctest`` does not check that the 
… 
… 

799  792  
800  793  sage: A = matrix(RDF, 8, range(64)) 
801  794  sage: U, S, V = A.SVD() 
802   sage: (U.transpose()*Uidentity_matrix(8)).norm() # abs tol 1e10 
 795  sage: (U.transpose()*Uidentity_matrix(8)).norm(p=2) # abs tol 1e10 
803  796  0.0 
804  797  
805  798  The 8th cyclotomic field is generated by the complex number 
… 
… 

814  807  
815  808  :: 
816  809  
817   sage: K = CyclotomicField(8) 
818   sage: g = K.gen(0); g 
819   zeta8 
 810  sage: K.<zeta8> = CyclotomicField(8) 
820  811  sage: N(zeta8) # absolute tolerance 1e15 
821  812  0.707106781186548 + 0.707106781186547*I 
822  813  
… 
… 

824  815  the root should normally print as ``1e+16``, or something similar. 
825  816  However, the tolerance testing causes the doctest framework to 
826  817  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`. 
828  820  
829  821  :: 
830  822  
831  823  sage: y = polygen(RDF, 'y') 
832   sage: p = (y  10^16)*(y10^(13))*(y2); p 
833   y^3 + (1e+16)*y^2 + (2e+16)*y  2000.0 
 824  sage: p = (y  10^16) * (y  10^13) * (y  2) 
834  825  sage: p.roots(multiplicities=False)[2] # relative tol 1e10 
835   10^16 
 826  1e16 
836  827  
837  828   If a line contains ``todo: not implemented``, it is never 
838  829  tested. It is good to include lines like this to make clear what we 