Fix some markup (including 2 false-positives).

[ezio-melotti]

This PR fixes markup errors exposed by sphinx-lint 0.6.3, even though two of them are actually false positives:

# Ignore the tools and venv dirs and check that the default role is not used.
./venv/bin/sphinx-lint -i tools -i ./venv --enable default-role
testing/coverage.rst:262: default role used (hint: for inline literals, use double backticks) (default-role)
documentation/style-guide.rst:154: default role used (hint: for inline literals, use double backticks) (default-role)
internals/parser.rst:836: default role used (hint: for inline literals, use double backticks) (default-role)
internals/parser.rst:837: default role used (hint: for inline literals, use double backticks) (default-role)
internals/parser.rst:838: default role used (hint: for inline literals, use double backticks) (default-role)

See also:

• Update sphinx-lint to 0.6.3 #956
• False positive for "--enable default-role" in 0.6.2 sphinx-contrib/sphinx-lint#46 (comment)

(cc @JulienPalard, @hugovk, @CAM-Gerlach)

[ezio-melotti]

This is a workaround for one of the two false positives. It's semantically (and syntactically) valid, and solves the error reported by sphinx-lint.

It is rendered as

with the variable part in italic.

[ezio-melotti]

These were actual errors.

[CAM-Gerlach]

Maybe just link the actual files (on GitHub instead)?

[JelleZijlstra]

That would be a good improvement for another PR.

[ezio-melotti]

• Add links to files in internals/parser.rst #960

[ezio-melotti]

This is another workaround: by reflowing the paragraph I avoid having the link and the ref on the same line.

[hugovk]

Maybe combine this with #956?

[ezio-melotti]

I'm planning to merge #956 just after this, but I wanted to make sure that these changes didn't trigger any errors with 0.6.1.

[CAM-Gerlach]

One minor optional comment, otherwise LGTM

[CAM-Gerlach]

Maybe just link the actual files (on GitHub instead)?

[CAM-Gerlach]

(Oops, wasn't showing as merged first)