src/tox.ini: Add validation of docstrings using flake8-rst-docstrings

[mkoeppe]

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

Depends on #30503

CC: @tobiasdiez @jhpalmieri @dimpase @fchapoton @DaveWitteMorris @Etn40ff @tscrim @kwankyu

Component: documentation

Author: Matthias Koeppe

Branch/Commit: 0677319

Reviewer: Kwankyu Lee

Issue created by migration from https://trac.sagemath.org/ticket/30448

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 047a845 to a4552e1

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

a4552e1

src/sage/coding: Fix some errors shown by tox -e rst

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from a4552e1 to 16c8046

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

3a6c1af	src/sage/cpython: Fix errors shown by tox -e rst
521a142	src/sage/doctest: Fix some errors shown by tox -e rst
c53c78c	src/sage/knots: Fix errors shown by tox -e rst
438d08b	src/sage/libs: Fix errors shown by tox -e rst
16c8046	src/sage/misc: Fix some errors shown by tox -e rst

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 16c8046 to 450cdc3

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

450cdc3

src/sage/modular: Fix some errors shown by tox -e rst

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

74738fb

src/sage/plot: Fix some errors shown by tox -e rst

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 450cdc3 to 74738fb

[mkoeppe]

Description changed:

--- 
+++ 
@@ -13,3 +13,4 @@
    ./sage -tox -e rst src/sage/geometry/polyhedra

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

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 74738fb to c2d0a91

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

dccceb4	src/sage/parallel: Fix errors shown by tox -e rst
4cc5674	src/sage/quadratic_forms: Fix errors shown by tox -e rst
a2f5ef6	src/sage/repl: Fix some errors shown by tox -e rst
c2d0a91	src/sage/rings: Fix some errors shown by tox -e rst

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

8fc8776	src/sage/structure: Fix errors shown by tox -e rst
18121fe	src/sage/modules: Fix errors shown by tox -e rst

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from c2d0a91 to 18121fe

[mkoeppe]

comment:50

I stop here for now, contributions welcome

[mkoeppe]

comment:51

Remaining failures see https://github.com/sagemath/sagetrac-mirror/runs/7294638131?check_suite_focus=true

[kwankyu]

comment:52

Replying to @mkoeppe:

Remaining failures see https://github.com/sagemath/sagetrac-mirror/runs/7294638131?check_suite_focus=true

May I open a meta ticket to deal with them?

[mkoeppe]

comment:53

Good idea

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. New commits:

d66c66e

.github/workflows/lint.yml: Do not fail when rst checks fail

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Changed commit from 18121fe to d66c66e

[mkoeppe]

Changed author from Matthias Koeppe, ... to Matthias Koeppe

[kwankyu]

Changed author from Matthias Koeppe to Matthias Koeppe, ...

[kwankyu]

New commits:

d66c66e

.github/workflows/lint.yml: Do not fail when rst checks fail

[kwankyu]

Changed dependencies from #30503 to #30503; #34156

[kwankyu]

comment:57

Okay. I will open a separate ticket.

[kwankyu]

Changed dependencies from #30503; #34156 to #30503

[kwankyu]

comment:59

Here is the meta ticket: #34157

[kwankyu]

comment:60

Done. It is a ticket party. Whet your appetite.

[kwankyu]

comment:61

Perhaps

diff --git a/src/sage/graphs/domination.py b/src/sage/graphs/domination.py
index 25ac512233..8cc1e57de9 100644
--- a/src/sage/graphs/domination.py
+++ b/src/sage/graphs/domination.py
@@ -513,7 +513,7 @@ def _cand_ext_enum(G, to_dom, u_next):

         .. WARNING::

-            The same output may be output several times (up to ``H`` times).
+            The same output may be output several times (up to `|H|` times).

         In order to later remove duplicates, we here output pairs ``(ext, i)``
         where ``ext`` is the output candidate extension and ``i`` counts how
@@ -593,7 +593,7 @@ def minimal_dominating_sets(G, to_dominate=None, work_on_copy=True):
     - ``work_on_copy`` -- boolean (default: ``True``); whether or not to work on
       a copy of the input graph; if set to ``False``, the input graph will be
       modified (relabeled).
-    
+
     OUTPUT:

     An iterator over the inclusion-minimal sets of vertices of ``G``.

[mkoeppe]

comment:62

Thanks for catching this, please push it to the ticket

[kwankyu]

Changed branch from u/mkoeppe/src_tox_ini__add_validation_of_rst_files_and_docstrings to public/30448

[kwankyu]

Changed commit from d66c66e to none

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Branch pushed to git repo; I updated commit sha1. Last 10 new commits:

450cdc3	src/sage/modular: Fix some errors shown by tox -e rst
74738fb	src/sage/plot: Fix some errors shown by tox -e rst
dccceb4	src/sage/parallel: Fix errors shown by tox -e rst
4cc5674	src/sage/quadratic_forms: Fix errors shown by tox -e rst
a2f5ef6	src/sage/repl: Fix some errors shown by tox -e rst
c2d0a91	src/sage/rings: Fix some errors shown by tox -e rst
8fc8776	src/sage/structure: Fix errors shown by tox -e rst
18121fe	src/sage/modules: Fix errors shown by tox -e rst
d66c66e	.github/workflows/lint.yml: Do not fail when rst checks fail
0677319	Fix a typo

[7ed8c4ca-6d56-4ae9-953a-41e42b4ed313]

Commit: 0677319

[kwankyu]

comment:65

Otherwise, it looks good to me.

[kwankyu]

Changed author from Matthias Koeppe, ... to Matthias Koeppe

[kwankyu]

Reviewer: Kwankyu Lee

[kwankyu]

Description changed:

--- 
+++ 
@@ -14,3 +14,5 @@

We also run it as part of the Lint workflow on GH Actions (see badge). + +Continued in the meta ticket: #34157

[mkoeppe]

comment:67

Thanks!

[jhpalmieri]

comment:68

A bug in flake8-rst-docstrings? See #34168 comment:14, also #34167 and #34169.

[jhpalmieri]

comment:69

Or maybe we're just sloppy in how we use reStructuredText, and we should add explicit titles our files, like

diff --git a/src/sage/categories/category_with_axiom.py b/src/sage/categories/category_with_axiom.py
index 237ad5dfed..d11bf0fe8a 100644
--- a/src/sage/categories/category_with_axiom.py
+++ b/src/sage/categories/category_with_axiom.py
@@ -1,5 +1,7 @@
 r"""
+======
 Axioms
+======

 This documentation covers how to implement axioms and proceeds with an
 overview of the implementation of the axiom infrastructure. It assumes

I don't know rst syntax well enough to know if a single word at the start of a text block has special significance, but I think it might. This might also explain the issue with "noreplace" in sagedoc.py in #34172.

[jhpalmieri]

comment:70

I can't get the syntax

======
Axioms
======

to compile: it yields an error. At #34168 we've diagnosed what looks like a bug in flake8-rst-docstrings, and fixing that would be my preferred resolution.

[vbraun]

Changed branch from public/30448 to 0677319