Trac #30448: src/tox.ini: Add validation of docstrings using flake8-r…

…st-docstrings

Short of running a single-file docbuild (which needs fixing - #30475),
there are several options for validating rst files and docstrings:

- https://pypi.org/project/rstcheck/
- https://pypi.org/project/doc8/
- https://pypi.org/project/flake8-rst-docstrings
- ​https://pypi.org/project/flake8-docstrings/ (uses
​https://github.com/pycqa/pydocstyle)

Here we add a tox environment using https://pypi.org/project/flake8-rst-
docstrings.

Usage:
{{{
   ./sage -tox -e rst src/sage/geometry/polyhedra
}}}

We also run it as part of the Lint workflow on GH Actions (see badge).

Continued in the meta ticket: #34157

URL: https://trac.sagemath.org/30448
Reported by: mkoeppe
Ticket author(s): Matthias Koeppe
Reviewer(s): Kwankyu Lee

.github/workflows/lint.yml

@@ -36,3 +36,19 @@ jobs:
       run: pip install tox relint
     - name: Lint using relint
       run: tox -e relint src/sage/
+  lint-rst:
+    name: Validate docstring markup as RST
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Install tox
+      run: pip install tox
+    - name: Lint using tox -e rst
+      run: tox -e rst
+      # Until all errors are fixed:
+      continue-on-error: true

src/sage/categories/category_with_axiom.py

@@ -2352,7 +2352,7 @@ def __reduce__(self):
         additive magma is implemented as
         ``MagmasAndAdditiveMagmas.Distributive.AdditiveAssociative.AdditiveCommutative``
         and not
-        ``MagmasAndAdditiveMagmas.Distributive.AdditiveCommutative.AdditiveAssociative``::
+        ``MagmasAndAdditiveMagmas.Distributive.AdditiveCommutative.AdditiveAssociative``.
 
         EXAMPLES::
 

src/sage/categories/chain_complexes.py

@@ -235,7 +235,7 @@ def _apply_functor_to_morphism(self, f):
         r"""
         Apply ``self`` to a chain map.
 
-        TESTS:
+        TESTS::
 
             sage: E3 = EuclideanSpace(3)                        # optional - sage.symbolic
             sage: C = E3.de_rham_complex()                      # optional - sage.symbolic

src/sage/categories/enumerated_sets.py

@@ -179,7 +179,7 @@ def __iter__(self):
 
             If none of these are provided, raise a ``NotImplementedError``.
 
-            EXAMPLES::
+            EXAMPLES:
 
             We start with an example where nothing is implemented::
 

src/sage/categories/modules_with_basis.py

@@ -2166,7 +2166,7 @@ def __call_on_basis__(self, **options):
                     sage: phi(x[1] + x[2] + x[3])
                     B[1] + 4*B[2] + 9*B[3]
 
-                TESTS::
+                TESTS:
 
                 As for usual homsets, the argument can be a Python function::
 

src/sage/categories/sets_cat.py

@@ -1471,10 +1471,10 @@ def construction(self):
 
         def _test_construction(self, **options):
             """
-            Test that the construction returned by self really yields self.
+            Test that the construction returned by ``self`` really yields ``self``.
 
-            :meth:`construction` either returns None or a pair ``(F,O)``,
-            and if it returns the latter, then it is supposed that ``F(O)==self`.
+            :meth:`construction` either returns None or a pair ``(F, O)``,
+            and if it returns the latter, then it is supposed that ``F(O) == self``.
             The test verifies this assumption.
 
             EXAMPLES:

src/sage/coding/delsarte_bounds.py

@@ -678,29 +678,29 @@ def delsarte_bound_Q_matrix(q, d, return_data=False, solver="PPL", isinteger=Fal
       (ILP), rather that an LP solver. Can be very slow if set to
       ``True``.
 
-   EXAMPLES:
+    EXAMPLES:
 
-   The bound on dimension of linear `F_2`-codes of length 10 and minimal distance 6::
+    The bound on dimension of linear `F_2`-codes of length 10 and minimal distance 6::
 
-       sage: q_matrix = Matrix([[codes.bounds.krawtchouk(10,2,i,j) for i in range(11)] for j in range(11)])
-       sage: codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6)
-       2
+        sage: q_matrix = Matrix([[codes.bounds.krawtchouk(10,2,i,j) for i in range(11)] for j in range(11)])
+        sage: codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6)
+        2
 
-       sage: a,p,val = codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6, return_data=True)
-       sage: [j for i,j in p.get_values(a).items()]
-       [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
+        sage: a,p,val = codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6, return_data=True)
+        sage: [j for i,j in p.get_values(a).items()]
+        [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
 
-   TESTS:
+    TESTS:
 
-       cases for using Hamming scheme Q matrix::
+    Cases for using Hamming scheme Q matrix::
 
-       sage: q_matrix = Matrix([[codes.bounds.krawtchouk(10,2,i,j) for i in range(11)] for j in range(11)])
-       sage: codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6)
-       2
+        sage: q_matrix = Matrix([[codes.bounds.krawtchouk(10,2,i,j) for i in range(11)] for j in range(11)])
+        sage: codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6)
+        2
 
-       sage: a,p,val = codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6, return_data=True)
-       sage: [j for i,j in p.get_values(a).items()]
-       [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
+        sage: a,p,val = codes.bounds.delsarte_bound_Q_matrix(q_matrix, 6, return_data=True)
+        sage: [j for i,j in p.get_values(a).items()]
+        [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]
 
     """
 

src/sage/coding/gabidulin_code.py

@@ -45,13 +45,13 @@ class GabidulinCode(AbstractLinearRankMetricCode):
 
     EXAMPLES:
 
-        A Gabidulin Code can be constructed in the following way:
+    A Gabidulin Code can be constructed in the following way::
 
-            sage: Fqm = GF(16)
-            sage: Fq = GF(4)
-            sage: C = codes.GabidulinCode(Fqm, 2, 2, Fq)
-            sage: C
-            [2, 2, 1] linear Gabidulin code over GF(16)/GF(4)
+        sage: Fqm = GF(16)
+        sage: Fq = GF(4)
+        sage: C = codes.GabidulinCode(Fqm, 2, 2, Fq)
+        sage: C
+        [2, 2, 1] linear Gabidulin code over GF(16)/GF(4)
     """
     _registered_encoders = {}
     _registered_decoders = {}
@@ -113,7 +113,7 @@ def __init__(self, base_field, length, dimension, sub_field=None,
             ValueError: 'length' can be at most the degree of the extension, 3
 
         If the number of evaluation points is not equal to the length
-        of the code, an error is raised:
+        of the code, an error is raised::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5)
@@ -125,7 +125,7 @@ def __init__(self, base_field, length, dimension, sub_field=None,
             ValueError: the number of evaluation points should be equal to the length of the code
 
         If evaluation points are not linearly independent over the ``base_field``,
-        an error is raised:
+        an error is raised::
 
             sage: evals = [ aa*i for i in range(2) ]
             sage: C = codes.GabidulinCode(Fqm, 2, 2, Fq, None, evals)
@@ -134,7 +134,7 @@ def __init__(self, base_field, length, dimension, sub_field=None,
             ValueError: the evaluation points provided are not linearly independent
 
         If an evaluation point does not belong to the ``base_field``, an error
-        is raised:
+        is raised::
 
             sage: a = GF(3).gen()
             sage: evals = [ a*i for i in range(2) ]
@@ -146,7 +146,7 @@ def __init__(self, base_field, length, dimension, sub_field=None,
         Given that both ``sub_field`` and ``twisting_homomorphism`` are specified
         and ``twisting_homomorphism`` has a fixed field method. If the fixed
         field of ``twisting_homomorphism`` is not ``sub_field``, an error is
-        raised:
+        raised::
 
             sage: Fqm = GF(64)
             sage: Fq = GF(8)
@@ -158,7 +158,7 @@ def __init__(self, base_field, length, dimension, sub_field=None,
 
         If ``twisting_homomorphism`` is given, but ``sub_field`` is not. In case
         ``twisting_homomorphism`` does not have a fixed field method, and error
-        is raised:
+        is raised::
 
             sage: Fqm.<z6> = GF(64)
             sage: sigma = Hom(Fqm, Fqm)[1]; sigma
@@ -417,7 +417,7 @@ def __init__(self, code):
 
         TESTS:
 
-        If the code is not a Gabidulin code, an error is raised:
+        If the code is not a Gabidulin code, an error is raised::
 
             sage: C = codes.HammingCode(GF(4), 2)
             sage: E = codes.encoders.GabidulinVectorEvaluationEncoder(C)
@@ -433,7 +433,7 @@ def _repr_(self):
         """
         Return a string representation of ``self``.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5^4)
@@ -447,7 +447,7 @@ def _latex_(self):
         r"""
         Return a latex representation of ``self``.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5^4)
@@ -571,7 +571,7 @@ def __init__(self, code):
 
         TESTS:
 
-        If the code is not a Gabidulin code, an error is raised:
+        If the code is not a Gabidulin code, an error is raised::
 
             sage: C = codes.HammingCode(GF(4), 2)
             sage: E = codes.encoders.GabidulinPolynomialEvaluationEncoder(C)
@@ -587,7 +587,7 @@ def _repr_(self):
         """
         Return a string representation of ``self``.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5^4)
@@ -601,7 +601,7 @@ def _latex_(self):
         r"""
         Return a latex representation of ``self``.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5^4)
@@ -648,7 +648,7 @@ def message_space(self):
         r"""
         Return the message space of the associated code of ``self``.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5^4)
@@ -680,7 +680,7 @@ def encode(self, p, form="vector"):
 
         - a codeword corresponding to `p` in vector or matrix form
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(2^9)
             sage: Fq = GF(2^3)
@@ -749,7 +749,7 @@ def unencode_nocheck(self, c):
 
         - a skew polynomial of degree less than ``self.code().dimension()``
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(2^9)
             sage: Fq = GF(2^3)
@@ -800,7 +800,7 @@ def __init__(self, code):
 
         TESTS:
 
-        If the code is not a Gabidulin code, an error is raised:
+        If the code is not a Gabidulin code, an error is raised::
 
             sage: C = codes.HammingCode(GF(4), 2)
             sage: D = codes.decoders.GabidulinGaoDecoder(C)
@@ -816,7 +816,7 @@ def _repr_(self):
         """
         Return a string representation of ``self``.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5^4)
@@ -830,7 +830,7 @@ def _latex_(self):
         r"""
         Return a latex representation of ``self``.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5^4)
@@ -894,7 +894,7 @@ def _partial_xgcd(self, a, b, d_stop):
 
         - ``u_c`` -- right linearized quotient of `a` and `b`
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(2^9)
             sage: Fq = GF(2^3)
@@ -942,7 +942,7 @@ def _decode_to_code_and_message(self, r):
         - the decoded codeword and decoded message corresponding to
           the received codeword `r`
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(2^9)
             sage: Fq = GF(2^3)
@@ -993,7 +993,7 @@ def decode_to_code(self, r):
 
         - the decoded codeword corresponding to the received codeword
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(3^20)
             sage: Fq = GF(3)
@@ -1026,7 +1026,7 @@ def decode_to_message(self, r):
 
         - the message corresponding to the received codeword
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(2^9)
             sage: Fq = GF(2^3)
@@ -1047,7 +1047,7 @@ def decoding_radius(self):
         """
         Return the decoding radius of the Gabidulin Gao Decoder.
 
-        EXAMPLES:
+        EXAMPLES::
 
             sage: Fqm = GF(5^20)
             sage: Fq = GF(5)

src/sage/coding/linear_code.py

@@ -2274,9 +2274,10 @@ def __init__(self, generator, d=None):
             sage: C.minimum_distance()
             3
 
-        We can construct a linear code directly from a vector space
-            sage: VS = matrix(GF(2), [[1,0,1],\
-                                      [1,0,1]]).row_space()
+        We can construct a linear code directly from a vector space::
+
+            sage: VS = matrix(GF(2), [[1,0,1],
+            ....:                     [1,0,1]]).row_space()
             sage: C = LinearCode(VS); C
             [3, 1] linear code over GF(2)
 

src/sage/cpython/_py2_random.py

@@ -471,7 +471,7 @@ def gammavariate(self, alpha, beta):
 
         Conditions on the parameters are alpha > 0 and beta > 0.
 
-        The probability distribution function is:
+        The probability distribution function is::
 
                     x ** (alpha - 1) * math.exp(-x / beta)
           pdf(x) =  --------------------------------------

src/sage/doctest/control.py

@@ -301,7 +301,7 @@ class Logger():
         'hello world\n'
     """
     def __init__(self, *files):
-        """
+        r"""
         Initialize the logger for writing to all files in ``files``.
 
         TESTS::

src/sage/functions/piecewise.py

@@ -108,7 +108,7 @@ def __call__(self, function_pieces, **kwds):
           domain and a symbolic function.
 
         - ``var=x`` -- a symbolic variable or ``None`` (default). The
-        real variable in which the function is piecewise in.
+          real variable in which the function is piecewise in.
 
         OUTPUT:
 

src/sage/game_theory/normal_form_game.py

@@ -1137,7 +1137,7 @@ def _gambit_(self, as_integer=False, maximization=True):
             { "" 3, 5, 8 }
             { "" 2, 6, 4 }
             }
-            1 2 3 4 5 6 7 8 
+            1 2 3 4 5 6 7 8
             <BLANKLINE>
         """
         from decimal import Decimal