Fix docstring markup in sage/groups and sage/misc

[kwankyu]

Part of #34157:

sage/groups/cubic_braid.py:1379:1: RST301 Unexpected indentation.
sage/groups/cubic_braid.py:1381:1: RST201 Block quote ends without a blank line; unexpected unindent.
sage/misc/sagedoc.py:594:1: RST214 Inline literal start-string without end-string.
sage/misc/sagedoc.py:670:1: RST214 Inline literal start-string without end-string.
sage/misc/profiler.py:63:1: RST303 Unknown directive type "todo".
sage/misc/sage_input.py:1840:1: RST215 Inline interpreted text or phrase reference start-string without end-string.
sage/misc/sage_input.py:1843:1: RST215 Inline interpreted text or phrase reference start-string without end-string.
sage/misc/sage_input.py:2139:1: RST215 Inline interpreted text or phrase reference start-string without end-string.
sage/misc/sage_input.py:2248:1: RST215 Inline interpreted text or phrase reference start-string without end-string.
sage/misc/call.py:112:1: RST205 Explicit markup ends without a blank line; unexpected unindent.

Depends on #30448

CC: @mkoeppe

Component: documentation

Author: John Palmieri

Branch/Commit: 5da5e1f

Reviewer: Matthias Koeppe

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

[jhpalmieri]

comment:2

I don't understand these:

sage/misc/sagedoc.py:594:1: RST214 Inline literal start-string without end-string.
sage/misc/sagedoc.py:670:1: RST214 Inline literal start-string without end-string.

They seem to come from ``noreplace``: if I change the text "noreplace" to anything else, the error goes away. I can make the change ``noreplace`` -> ``"noreplace"`` to "fix" it, but I don't know what's going on.

[jhpalmieri]

Branch: u/jhpalmieri/misc-doc-markup

[fchapoton]

Commit: 0794103

[fchapoton]

comment:4

noreplace seems to be our own directiev, as explained in the very same file.

Best solution should be to exclude this file from the rst validator.

---

New commits:

0794103

trac 34172: doc markup fixes for groups, misc

[fchapoton]

comment:5

hmm, at second thought, the problem is not in the first line of the doc. Strange indeed.

[jhpalmieri]

comment:6

Does the validator use any of Sage's code, or does it just use flake8-rst-docstrings? I really don't understand why noreplace is causing problems. (And the actual documentation looks fine.)

[mkoeppe]

comment:8

Replying to @jhpalmieri:

Does the validator use any of Sage's code, or does it just use flake8-rst-docstrings?

Only flake8-rst-docstrings with customization in src/tox.ini [flake8]

[jhpalmieri]

comment:9

Then I really have no idea what's going on with noreplace.

[mkoeppe]

comment:10

Replying to @fchapoton:

noreplace seems to be our own directiev, as explained in the very same file.

Best solution should be to exclude this file from the rst validator.

https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#in-line-ignoring-errors

https://flake8.pycqa.org/en/3.1.1/user/ignoring-errors.html#ignoring-entire-files

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. Last 10 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
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
56f5a50	Merge branch 't/30448/public/30448' into t/34172/misc-doc-markup
5da5e1f	trac 34172: ignore misc/sagedoc.py when using flake8 to check rst markup

[sagetrac-git]

Changed commit from 0794103 to 5da5e1f

[jhpalmieri]

comment:12

Let's ignore that file, then. (I can't figure out how to ignore a line in a docstring without the "# noqa ..." appearing in the documentation.)

[jhpalmieri]

Dependencies: 30448

[mkoeppe]

Author: John Palmieri

[mkoeppe]

Reviewer: Matthias Koeppe

[jhpalmieri]

comment:14

If the potential bug in flake8-rst-docstrings cited in #34168 gets fixed, then we can cease ignoring misc/sagedoc.py.

[vbraun]

Changed branch from u/jhpalmieri/misc-doc-markup to 5da5e1f