Meta ticket: fix docstring markups

[kwankyu]

Originated from #30448.

We fix

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

by chunks through

• Fix docstring markup in sage/game_theory #34156: sage/game_theory
• Fix docstring markup in sage/manifolds #34158: sage/manifolds
• Fix docstring markup in sage/modular #34159: sage/modular
• Fix docstring markup in sage/schemes #34160: sage/schemes
• Fix docstring markup in sage/databases #34161: sage/databases
• Fix docstring markup in sage/doctest #34162: sage/doctest
• Fix docstring markup in sage/interfaces #34163: sage/interfaces
• Fix docstring markup in sage/plot and sage/graphs #34164: sage/plot, sage/graphs
• Fix docstring markup in sage/tests/book_stein_modform.py #34165: sage/tests/book_stein_modform.py
• Fix docstring markup in sage/tests except sage/tests/book_stein_modform.py #34166: sage/tests except sage/tests/book_stein_modform.py
• Fix docstring markup in sage/matroids, sage/geometry, sage/modules #34167: sage/matroids, sage/geometry, sage/modules
• Fix docstring markup in sage/categories #34168: sage/categories
• Fix docstring markup in sage/interacts and sage/rings #34169: sage/interacts and sage/rings
• Fix docstring markup in sage/coding #34170: sage/coding
• Fix docstring markup in sage/combinat #34171: sage/combinat
• Fix docstring markup in sage/groups and sage/misc #34172: sage/groups, sage/misc

and a few commits that finish the job here on the ticket.

Depends on #30448
Depends on #34156
Depends on #34158
Depends on #34159
Depends on #34160
Depends on #34161
Depends on #34162
Depends on #34163
Depends on #34164
Depends on #34165
Depends on #34166
Depends on #34167
Depends on #34168
Depends on #34169
Depends on #34170
Depends on #34171
Depends on #34172
Depends on #34139

CC: @tscrim @fchapoton

Component: documentation

Author: Matthias Koeppe

Branch/Commit: 3b9399d

Reviewer: Kwankyu Lee

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

[mkoeppe]

comment:18

What should we do with

sage/combinat/tutorial.py:20:1: RST303 Unknown directive type "todo".

Normalize all to TODO, or make the lower-case todo known to the linter?

[kwankyu]

comment:19

Replying to @mkoeppe:

What should we do with

sage/combinat/tutorial.py:20:1: RST303 Unknown directive type "todo".

(1) Normalize all to TODO, or
(2) make the lower-case todo known to the linter?

According to

https://doc.sagemath.org/html/en/developer/coding_basics.html#sage-documentation-style

TODO is preferred in sage. But I think todo should be at least known to the linter since sphinx doesn't care the case. So I am +1 to (2).

[jhpalmieri]

comment:20

Replying to @mkoeppe:

What should we do with

sage/combinat/tutorial.py:20:1: RST303 Unknown directive type "todo".

Normalize all to TODO, or make the lower-case todo known to the linter?

Probably both. People will write new code by imitating what they see in the old code, so the more we match the guidelines, the better.

(This is another case like the blank lines between list items where I don't see the point in having a strict guideline. In this case we actually have one in place, so we should follow it.)

[mkoeppe]

Branch: u/mkoeppe/meta_ticket__fix_docstring_markups

[sagetrac-git]

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

f2b44c5	rst fixes in rings and interacts
4950d2b	fix one detail
e713cec	Merge #34169

[sagetrac-git]

Commit: e713cec

[sagetrac-git]

Changed commit from e713cec to 48ad149

[sagetrac-git]

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

b37c1de	rst fixes in geometry matroids modules
918dfcd	Merge branch 't/30448/public/30448' into t/34167/34167
ecd5e1a	trac 34167: add MODULEAUTHOR, autofunction to the list of known directives
1c7f79a	Merge #34167
8f13a5a	rst fixes in interfaces/
c79ff66	fix details
48ad149	Merge #34163

[mkoeppe]

comment:24

To test with the bugfix release of the linter, regenerate the toxenv using
./sage -tox -r -e rst

[mkoeppe]

comment:25

Remaining failures:

sage/combinat/parallelogram_polyomino.py:430:1: RST213 Inline emphasis start-string without end-string.
sage/combinat/parallelogram_polyomino.py:430:1: RST210 Inline strong start-string without end-string.
sage/combinat/counting.py:2:1: RST399 Document or section may not begin with a transition.
sage/combinat/designs/database.py:20:1: RST202 Bullet list ends without a blank line; unexpected unindent.
sage/combinat/designs/database.py:25:1: RST202 Bullet list ends without a blank line; unexpected unindent.
sage/combinat/designs/database.py:28:1: RST202 Bullet list ends without a blank line; unexpected unindent.
sage/combinat/designs/database.py:31:1: RST202 Bullet list ends without a blank line; unexpected unindent.
sage/combinat/designs/database.py:37:1: RST202 Bullet list ends without a blank line; unexpected unindent.
sage/doctest/sources.py:765:1: RST214 Inline literal start-string without end-string.
sage/doctest/sources.py:765:1: RST214 Inline literal start-string without end-string.
sage/repl/interpreter.py:465:1: RST303 Unknown directive type "attribute".
sage/graphs/graph_plot.py:50:1: RST299 The "csv-table" directive requires content; none supplied.

[fchapoton]

comment:46

this should be extended to pyx files too

EDIT: see #34305

[slel]

comment:47

Please rebase.

[mkoeppe]

comment:48

No need, it merges cleanly with 9.7.beta8 when done manually

[vbraun]

Changed branch from u/mkoeppe/meta_ticket__fix_docstring_markups to 3b9399d