Document, lint, and fix placement of magic comments in multiline doctests

src/.relint.yml

@@ -52,3 +52,12 @@
   pattern: 'from\s+sage(|[.](arith|categories|combinat|ext|graphs(|[.]decompositions)|interfaces|libs|matrix|misc|numerical(|[.]backends)|rings(|[.]finite_rings)|sets))[.]all\s+import'
   # imports from .all are allowed in all.py; also allow in some modules that need sage.all
   filePattern: '(.*/|)(?!(all|benchmark|dev_tools|parsing|sage_eval))[^/.]*[.](py|pyx|pxi)$'
+
+# Magic doctest comments
+
+- name: 'multiline_doctest_comment: magic comment on a continuation line'
+  hint: |
+    magic doctest comments should appear on the "sage:" line, not "....:" lines
+  # see optional_regex in src/sage/doctest/parsing.py
+  # "indirect doctest" is from src/bin/sage-coverage
+  pattern: '^[ 	]*[.][.][.][.]:.*#.*(arb216|arb218|py2|py3|long time|not implemented|not tested|known bug|optional|indirect doctest)'

src/doc/en/constructions/plotting.rst

@@ -301,10 +301,10 @@ Here is an example of a plot of a parametric surface in 3-space:
 ::
 
     sage: maxima.plot3d_parametric(["v*sin(u)","v*cos(u)","v"], ["u","v"],
-    ....:     [-3.2,3.2],[0,3])      # optional -- pops up a window.
+    ....:     [-3.2,3.2],[0,3])
     sage: opts = '[gnuplot_term, ps], [gnuplot_out_file, "sin-cos-plot.eps"]'
     sage: maxima.plot3d_parametric(["v*sin(u)","v*cos(u)","v"], ["u","v"],
-    ....:     [-3.2,3.2],[0,3],opts)     # optional -- pops up a window.
+    ....:     [-3.2,3.2],[0,3],opts)
 
 To illustrate how to pass gnuplot options in , here is an example
 of a plot of a set of points involving the Riemann zeta function

src/doc/en/developer/coding_basics.rst

@@ -1092,9 +1092,9 @@ framework. Here is a comprehensive list:
 
       sage: print("The sum of 1 and 1 equals 5")  # abs tol 1
       The sum of 2 and 2 equals 4
-      sage: e^(i*pi/4).n() # rel tol 1e-1
+      sage: e^(i*pi/4).n()  # rel tol 1e-1
       0.7 + 0.7*I
-      sage: ((x+1.001)^4).expand() # rel tol 2
+      sage: ((x+1.001)^4).expand()  # rel tol 2
       x^4 + 4*x^3 + 6*x^2 + 4*x + 1
       sage: M = matrix.identity(3) + random_matrix(RR,3,3)/10^3
       sage: M^2 # abs tol 1e-2
@@ -1219,6 +1219,22 @@ framework. Here is a comprehensive list:
       8193                      # 32-bit
       2147491840                # 64-bit
 
+Per coding style (:ref:`section-coding-python`), the magic comment
+should be separated by at least 2 spaces.
+
+For multiline doctests, the comment should appear on the first
+`physical line <https://docs.python.org/3/reference/lexical_analysis.html#physical-lines>`_
+of the doctest (the line with the prompt ``sage:``), not on the
+continuation lines (the lines with the prompt ``....:``)::
+
+    sage: print(ZZ.random_element())        # random
+    42
+    sage: for _ in range(3):                # random
+    ....:     print(QQ.random_element())
+    1
+    1/77
+    -1/2
+
 Using ``search_src`` from the Sage prompt (or ``grep``), one can
 easily find the aforementioned keywords. In the case of ``todo: not
 implemented``, one can use the results of such a search to direct

src/doc/pt/tutorial/interfaces.rst

@@ -233,8 +233,8 @@ cálculos). Não digite ``...``:
 
     sage: x, y = QQ['x, y'].gens()
     sage: f = 9*y^8 - 9*x^2*y^7 - 18*x^3*y^6 - 18*x^5*y^6 + 9*x^6*y^4 \
-    ....:  + 18*x^7*y^5 + 36*x^8*y^4 + 9*x^10*y^4 - 18*x^11*y^2 - 9*x^12*y^3 \
-    ....:  - 18*x^13*y^2 + 9*x^16
+    ....:     + 18*x^7*y^5 + 36*x^8*y^4 + 9*x^10*y^4 - 18*x^11*y^2 - 9*x^12*y^3 \
+    ....:     - 18*x^13*y^2 + 9*x^16
     sage: factor(f)
     (9) * (-x^5 + y^2)^2 * (x^6 - 2*x^3*y^2 - x^2*y^3 + y^4)
 
@@ -305,38 +305,38 @@ Um gráfico em duas dimensões de diversas funções (não digite ``...``):
 
 ::
 
-    sage: maxima.plot2d('[cos(7*x),cos(23*x)^4,sin(13*x)^3]','[x,0,1]',  # not tested
-    ....: '[plot_format,openmath]') # not tested
+    sage: maxima.plot2d('[cos(7*x),cos(23*x)^4,sin(13*x)^3]', '[x,0,1]',  # not tested
+    ....:               '[plot_format,openmath]')
 
 Um gráfico em 3D que você pode mover com o seu mouse:
 
 ::
 
     sage: maxima.plot3d("2^(-u^2 + v^2)", "[u, -3, 3]", "[v, -2, 2]",  # not tested
-    ....: '[plot_format, openmath]') # not tested
+    ....:               '[plot_format, openmath]')
 
-    sage: maxima.plot3d("atan(-x^2 + y^3/4)", "[x, -4, 4]", "[y, -4, 4]", # not tested
-    ....: "[grid, 50, 50]",'[plot_format, openmath]') # not tested
+    sage: maxima.plot3d("atan(-x^2 + y^3/4)", "[x, -4, 4]", "[y, -4, 4]",  # not tested
+    ....:               "[grid, 50, 50]",'[plot_format, openmath]')
 
 O próximo gráfico é a famosa faixa de Möbious:
 
 ::
 
-    sage: maxima.plot3d("[cos(x)*(3 + y*cos(x/2)), sin(x)*(3 + y*cos(x/2))," \ # not tested
-    ....: "y*sin(x/2)]", "[x, -4, 4]", "[y, -4, 4]", # not tested
-    ....: '[plot_format, openmath]') # not tested
+    sage: maxima.plot3d("[cos(x)*(3 + y*cos(x/2)), sin(x)*(3 + y*cos(x/2)),"  # not tested
+    ....:               "y*sin(x/2)]", "[x, -4, 4]", "[y, -4, 4]",
+    ....:               '[plot_format, openmath]')
 
 E agora a famosa garrafa de Klein:
 
 ::
 
-    sage: maxima("expr_1: 5*cos(x)*(cos(x/2)*cos(y) + sin(x/2)*sin(2*y)+ 3.0)"\
-    ....: "- 10.0")
+    sage: maxima("expr_1: 5*cos(x)*(cos(x/2)*cos(y) + sin(x/2)*sin(2*y)+ 3.0)"
+    ....:        "- 10.0")
     5*cos(x)*(sin(x/2)*sin(2*y)+cos(x/2)*cos(y)+3.0)-10.0
     sage: maxima("expr_2: -5*sin(x)*(cos(x/2)*cos(y) + sin(x/2)*sin(2*y)+ 3.0)")
     -5*sin(x)*(sin(x/2)*sin(2*y)+cos(x/2)*cos(y)+3.0)
     sage: maxima("expr_3: 5*(-sin(x/2)*cos(y) + cos(x/2)*sin(2*y))")
     5*(cos(x/2)*sin(2*y)-sin(x/2)*cos(y))
     sage: maxima.plot3d("[expr_1, expr_2, expr_3]", "[x, -%pi, %pi]", # not tested
-    ....: "[y, -%pi, %pi]", "['grid, 40, 40]", # not tested
-    ....: '[plot_format, openmath]') # not tested
+    ....:               "[y, -%pi, %pi]", "['grid, 40, 40]",
+    ....:               '[plot_format, openmath]')

src/sage/calculus/ode.pyx

@@ -327,12 +327,12 @@ class ode_solver():
         sage: T = ode_solver()                               # not tested
         sage: T.algorithm = "bsimp"                          # not tested
         sage: vander = van_der_pol()                         # not tested
-        sage: T.function=vander                              # not tested
-        sage: T.ode_solve(y_0 = [1,0], t_span=[0,2000],      # not tested
-        ....:             num_points=1000)                   # not tested
+        sage: T.function = vander                            # not tested
+        sage: T.ode_solve(y_0=[1, 0], t_span=[0, 2000],      # not tested
+        ....:             num_points=1000)
         sage: from tempfile import NamedTemporaryFile        # not tested
         sage: with NamedTemporaryFile(suffix=".png") as f:   # not tested
-        ....:     T.plot_solution(i=0, filename=f.name)      # not tested
+        ....:     T.plot_solution(i=0, filename=f.name)
 
     """
     def __init__(self,function=None,jacobian=None,h = 1e-2,error_abs=1e-10,error_rel=1e-10, a=False,a_dydt=False,scale_abs=False,algorithm="rkf45",y_0=None,t_span=None,params = []):

src/sage/categories/complex_reflection_or_generalized_coxeter_groups.py

@@ -197,7 +197,7 @@ def simple_reflection(self, i):
 
                 sage: W = ReflectionGroup((1,1,4), index_set=[1,3,'asdf'])  # optional - gap3
                 sage: for i in W.index_set():                           # optional - gap3
-                ....:     print('%s %s'%(i, W.simple_reflection(i)))    # optional - gap3
+                ....:     print('%s %s'%(i, W.simple_reflection(i)))
                 1 (1,7)(2,4)(5,6)(8,10)(11,12)
                 3 (1,4)(2,8)(3,5)(7,10)(9,11)
                 asdf (2,5)(3,9)(4,6)(8,11)(10,12)
@@ -447,7 +447,7 @@ def reflection(self, i):
 
                 sage: W = ReflectionGroup((1,1,4))                      # optional - gap3
                 sage: for i in W.reflection_index_set():                # optional - gap3
-                ....:     print('%s %s'%(i, W.reflection(i)))           # optional - gap3
+                ....:     print('%s %s'%(i, W.reflection(i)))
                 1 (1,7)(2,4)(5,6)(8,10)(11,12)
                 2 (1,4)(2,8)(3,5)(7,10)(9,11)
                 3 (2,5)(3,9)(4,6)(8,11)(10,12)
@@ -472,30 +472,30 @@ def reflections(self):
                 sage: W = ReflectionGroup((1,1,3))                      # optional - gap3
                 sage: reflections = W.reflections()                     # optional - gap3
                 sage: for index in sorted(reflections.keys()):          # optional - gap3
-                ....:     print('%s %s'%(index, reflections[index]))    # optional - gap3
+                ....:     print('%s %s'%(index, reflections[index]))
                 1 (1,4)(2,3)(5,6)
                 2 (1,3)(2,5)(4,6)
                 3 (1,5)(2,4)(3,6)
 
                 sage: W = ReflectionGroup((1,1,3),reflection_index_set=['a','b','c'])   # optional - gap3
                 sage: reflections = W.reflections()                     # optional - gap3
                 sage: for index in sorted(reflections.keys()):          # optional - gap3
-                ....:     print('%s %s'%(index, reflections[index]))    # optional - gap3
+                ....:     print('%s %s'%(index, reflections[index]))
                 a (1,4)(2,3)(5,6)
                 b (1,3)(2,5)(4,6)
                 c (1,5)(2,4)(3,6)
 
                 sage: W = ReflectionGroup((3,1,1))                      # optional - gap3
                 sage: reflections = W.reflections()                     # optional - gap3
                 sage: for index in sorted(reflections.keys()):          # optional - gap3
-                ....:     print('%s %s'%(index, reflections[index]))    # optional - gap3
+                ....:     print('%s %s'%(index, reflections[index]))
                 1 (1,2,3)
                 2 (1,3,2)
 
                 sage: W = ReflectionGroup((1,1,3), (3,1,2))             # optional - gap3
                 sage: reflections = W.reflections()                     # optional - gap3
                 sage: for index in sorted(reflections.keys()):          # optional - gap3
-                ....:     print('%s %s'%(index, reflections[index]))    # optional - gap3
+                ....:     print('%s %s'%(index, reflections[index]))
                 1 (1,6)(2,5)(7,8)
                 2 (1,5)(2,7)(6,8)
                 3 (3,9,15)(4,10,16)(12,17,23)(14,18,24)(20,25,29)(21,22,26)(27,28,30)
@@ -562,7 +562,7 @@ def distinguished_reflection(self, i):
 
                 sage: W = ReflectionGroup((1,1,4), hyperplane_index_set=('a','b','c','d','e','f'))  # optional - gap3
                 sage: for i in W.hyperplane_index_set():                    # optional - gap3
-                ....:     print('%s %s'%(i, W.distinguished_reflection(i))) # optional - gap3
+                ....:     print('%s %s'%(i, W.distinguished_reflection(i)))
                 a (1,7)(2,4)(5,6)(8,10)(11,12)
                 b (1,4)(2,8)(3,5)(7,10)(9,11)
                 c (2,5)(3,9)(4,6)(8,11)(10,12)
@@ -596,29 +596,29 @@ def distinguished_reflections(self):
                 sage: W = ReflectionGroup((1,1,3))                      # optional - gap3
                 sage: distinguished_reflections = W.distinguished_reflections() # optional - gap3
                 sage: for index in sorted(distinguished_reflections.keys()):        # optional - gap3
-                ....:     print('%s %s'%(index, distinguished_reflections[index]))  # optional - gap3
+                ....:     print('%s %s'%(index, distinguished_reflections[index]))
                 1 (1,4)(2,3)(5,6)
                 2 (1,3)(2,5)(4,6)
                 3 (1,5)(2,4)(3,6)
 
                 sage: W = ReflectionGroup((1,1,3),hyperplane_index_set=['a','b','c'])   # optional - gap3
                 sage: distinguished_reflections = W.distinguished_reflections() # optional - gap3
                 sage: for index in sorted(distinguished_reflections.keys()):        # optional - gap3
-                ....:     print('%s %s'%(index, distinguished_reflections[index]))  # optional - gap3
+                ....:     print('%s %s'%(index, distinguished_reflections[index]))
                 a (1,4)(2,3)(5,6)
                 b (1,3)(2,5)(4,6)
                 c (1,5)(2,4)(3,6)
 
                 sage: W = ReflectionGroup((3,1,1))                      # optional - gap3
                 sage: distinguished_reflections = W.distinguished_reflections() # optional - gap3
                 sage: for index in sorted(distinguished_reflections.keys()):        # optional - gap3
-                ....:     print('%s %s'%(index, distinguished_reflections[index]))  # optional - gap3
+                ....:     print('%s %s'%(index, distinguished_reflections[index]))
                 1 (1,2,3)
 
                 sage: W = ReflectionGroup((1,1,3), (3,1,2))             # optional - gap3
                 sage: distinguished_reflections = W.distinguished_reflections() # optional - gap3
                 sage: for index in sorted(distinguished_reflections.keys()):    # optional - gap3
-                ....:     print('%s %s'%(index, distinguished_reflections[index]))  # optional - gap3
+                ....:     print('%s %s'%(index, distinguished_reflections[index]))
                 1 (1,6)(2,5)(7,8)
                 2 (1,5)(2,7)(6,8)
                 3 (3,9,15)(4,10,16)(12,17,23)(14,18,24)(20,25,29)(21,22,26)(27,28,30)

src/sage/categories/finite_complex_reflection_groups.py

@@ -898,7 +898,7 @@ def generalized_noncrossing_partitions(self, m, c=None, positive=False):
                     sage: W = ReflectionGroup((1,1,3))                          # optional - gap3
 
                     sage: sorted([w.reduced_word() for w in chain]              # optional - gap3
-                    ....:        for chain in W.generalized_noncrossing_partitions(2))  # optional - gap3
+                    ....:        for chain in W.generalized_noncrossing_partitions(2))
                     [[[], [], [1, 2]],
                      [[], [1], [2]],
                      [[], [1, 2], []],
@@ -913,7 +913,7 @@ def generalized_noncrossing_partitions(self, m, c=None, positive=False):
                      [[2], [1, 2, 1], []]]
 
                     sage: sorted([w.reduced_word() for w in chain]              # optional - gap3
-                    ....:        for chain in W.generalized_noncrossing_partitions(2, positive=True))   # optional - gap3
+                    ....:        for chain in W.generalized_noncrossing_partitions(2, positive=True))
                     [[[], [1, 2], []],
                      [[], [1, 2, 1], [1]],
                      [[1], [2], []],

src/sage/combinat/abstract_tree.py

@@ -1937,8 +1937,8 @@ def __setitem_rec__(self, idx, i, value):
         TESTS::
 
             sage: x = OrderedTree([[[], []],[[]]])
-            sage: with x.clone() as x:
-            ....:     x[0,1] = OrderedTree([[[]]]) # indirect doctest
+            sage: with x.clone() as x:              # indirect doctest
+            ....:     x[0,1] = OrderedTree([[[]]])
             sage: x
             [[[], [[[]]]], [[]]]
         """

src/sage/combinat/crystals/alcove_path.py

@@ -193,9 +193,9 @@ class CrystalOfAlcovePaths(UniqueRepresentation, Parent):
         sage: K = crystals.KirillovReshetikhin(['B',3,1],2,1)
         sage: T = crystals.TensorProduct(K,K)
         sage: g = T.digraph() #long time
-        sage: for e in g.edges(sort=False): #long time
-        ....:     if e[0].phi(0) == 1 and e[2] == 0: #long time
-        ....:         g.delete_edge(e)  #long time
+        sage: for e in g.edges(sort=False):  #long time
+        ....:     if e[0].phi(0) == 1 and e[2] == 0:
+        ....:         g.delete_edge(e)
 
         sage: C = crystals.AlcovePaths(['B',3,1],[0,2,0], highest_weight_crystal=False)
         sage: g2 = C.digraph() #long time

src/sage/combinat/designs/bibd.py

@@ -772,8 +772,8 @@ def v_4_1_BIBD(v, check=True):
 
         sage: from sage.combinat.designs.bibd import v_4_1_BIBD  # long time
         sage: for n in range(13,100):                            # long time
-        ....:    if n%12 in [1,4]:                               # long time
-        ....:       _ = v_4_1_BIBD(n, check = True)              # long time
+        ....:    if n%12 in [1,4]:
+        ....:       _ = v_4_1_BIBD(n, check = True)
 
     TESTS:
 
@@ -787,8 +787,8 @@ def v_4_1_BIBD(v, check=True):
     Check some larger `(v,4,1)`-BIBD (see :trac:`17557`)::
 
         sage: for v in range(400):                                      # long time
-        ....:     if v%12 in [1,4]:                                     # long time
-        ....:         _ = designs.balanced_incomplete_block_design(v,4) # long time
+        ....:     if v%12 in [1,4]:
+        ....:         _ = designs.balanced_incomplete_block_design(v,4)
     """
     k = 4
     if v == 0:
@@ -1262,7 +1262,7 @@ def BIBD_5q_5_for_q_prime_power(q):
 
         sage: from sage.combinat.designs.bibd import BIBD_5q_5_for_q_prime_power
         sage: for q in [25, 45, 65, 85, 125, 145, 185, 205, 305, 405, 605]: # long time
-        ....:     _ = BIBD_5q_5_for_q_prime_power(q/5)                      # long time
+        ....:     _ = BIBD_5q_5_for_q_prime_power(q/5)
     """
     from sage.rings.finite_rings.finite_field_constructor import FiniteField
 

src/sage/combinat/designs/incidence_structures.py

@@ -2201,7 +2201,7 @@ def _latex_(self):
             # verify that :trac:`30976` is fixed
             sage: IS = IncidenceStructure([1,2,3], [[1,2], [2,3]])
             sage: if latex.has_file("tikz.sty"):          # optional - latex
-            ....:     IS._latex_()                        # optional - latex
+            ....:     IS._latex_()
             ...UserWarning:
             The hypergraph is drawn as a set of closed curves...
             \begin{tikzpicture}...

src/sage/combinat/designs/orthogonal_arrays.py

@@ -1183,7 +1183,7 @@ def incomplete_orthogonal_array(k,n,holes,resolvable=False, existence=False):
         sage: iOA = designs.incomplete_orthogonal_array(10,153,[9]*10)  # long time
         sage: OA9 = designs.orthogonal_arrays.build(10,9)               # long time
         sage: for i in range(10):                                       # long time
-        ....:     iOA.extend([[153-9*(i+1)+x for x in B] for B in OA9]) # long time
+        ....:     iOA.extend([[153-9*(i+1)+x for x in B] for B in OA9])
         sage: is_orthogonal_array(iOA,10,153)                           # long time
         True
 

src/sage/combinat/designs/orthogonal_arrays_build_recursive.py

@@ -668,8 +668,8 @@ def thwart_lemma_3_5(k,n,m,a,b,c,d=0,complement=False,explain_construction=False
         ....:    [10, 13, 78, 9, 9, 13, 1],
         ....:    [10, 13, 79, 9, 9, 13, 1]]
         sage: for k,n,m,a,b,c,d in l:                                       # not tested -- too long
-        ....:     OA = thwart_lemma_3_5(k,n,m,a,b,c,d,complement=True)      # not tested -- too long
-        ....:     assert is_orthogonal_array(OA,k,n*m+a+b+c+d,verbose=True) # not tested -- too long
+        ....:     OA = thwart_lemma_3_5(k,n,m,a,b,c,d,complement=True)
+        ....:     assert is_orthogonal_array(OA,k,n*m+a+b+c+d,verbose=True)
 
         sage: print(designs.orthogonal_arrays.explain_construction(10,1046))
         Lemma 3.5 with n=13,m=79,a=9,b=1,c=0,d=9 from:

src/sage/combinat/designs/orthogonal_arrays_find_recursive.pyx

@@ -541,7 +541,7 @@ cpdef find_thwart_lemma_3_5(int k,int N):
         12 3994 (12, 19, 207, 16, 13, 13, 19, True)
 
         sage: for k,n in kn:                                                     # not tested -- too long
-        ....:     assert designs.orthogonal_array(k,n,existence=True) is True    # not tested -- too long
+        ....:     assert designs.orthogonal_array(k,n,existence=True) is True
     """
     from .orthogonal_arrays_build_recursive import thwart_lemma_3_5
     cdef int n,m,a,b,c,d,NN,na,nb,nc

src/sage/combinat/designs/resolvable_bibd.py

@@ -399,9 +399,9 @@ def v_4_1_rbibd(v,existence=False):
 
     TESTS::
 
-        sage: for q in prime_powers(2,30):
+        sage: for q in prime_powers(2,30):  # indirect doctest
         ....:     if (3*q+1)%12 == 4:
-        ....:         _ = designs.resolvable_balanced_incomplete_block_design(3*q+1,4) # indirect doctest
+        ....:         _ = designs.resolvable_balanced_incomplete_block_design(3*q+1,4)
     """
     # Volume 1, VII.7.5.a from [BJL99]_
     if v%3 != 1 or not is_prime_power((v-1)//3):

src/sage/combinat/designs/steiner_quadruple_systems.py

@@ -705,8 +705,8 @@ def steiner_quadruple_system(n, check = False):
     TESTS::
 
         sage: for n in range(4, 100):                                      # long time
-        ....:     if (n%6) in [2,4]:                                        # long time
-        ....:         sqs = designs.steiner_quadruple_system(n, check=True) # long time
+        ....:     if (n%6) in [2,4]:
+        ....:         sqs = designs.steiner_quadruple_system(n, check=True)
     """
     n = int(n)
     if not ((n%6) in [2, 4]):