Replace doclinter with sphinx-lint

[JulienPalard]

Subject: Just ran sphinx-lint on Sphinx own doc.

Unsurprisingly I found more issues in sphinx-lint than in Sphinx doc while doing so ;-)

But it found a real one:

-   For Sphinx version 3.5.1 beta 3 this would be `(3, 5, 1, 'beta', 3)``.
+   For Sphinx version 3.5.1 beta 3 this would be ``(3, 5, 1, 'beta', 3)``.

so I'm happy. Other things were trailing whitespaces, and so on.

[AA-Turner]

Is sphinx-lint at a point where we can add it to CI for core Sphinx?

A

[JulienPalard]

Is sphinx-lint at a point where we can add it to CI for core Sphinx?

Yes, multiple projects already does it (cpython, pandas, sympy, ...) but I would recommend not having it mandatory yet for Sphinx, as it's typically here that we can find surprising things like rst-in-rst ;)

Do you want me to add the github workflow in the same PR?

[AA-Turner]

Do you want me to add the github workflow in the same PR?

Please, currently Sphinx uses a custom linter via tox:

sphinx/tox.ini

Lines 88 to 95 in 5eeeb9c

	[testenv:docslint]
	basepython = python3
	description =
	Lint documentation.
	extras =
	docs
	commands =
	python utils/doclinter.py CHANGES CONTRIBUTING.rst README.rst doc/

I think using a standard tool would be beneficial.

A

[JulienPalard]

Updated the Makefile:

$ make doclinter
sphinx-lint CHANGES *.rst doc/
No problems found.

Updated tox.ini:

$ tox -e docslint
docslint create: /home/mdk/clones/sphinx/.tox/docslint
docslint develop-inst: /home/mdk/clones/sphinx
[...]
docslint run-test-pre: PYTHONHASHSEED='2544686718'
docslint run-test: commands[0] | sphinx-lint CHANGES CONTRIBUTING.rst README.rst doc/
No problems found.
_____________________________________________________________________________________________________ summary _____________________________________________________________________________________________________
  docslint: commands succeeded
  congratulations :)

And Github Actions side I just bumped the Python version from 3.6 to 3.7 in the lint workflow, because sphinx-lint requires it.

[JulienPalard]

CI fails due to psf/requests#6140.

[JulienPalard]

The CI could probably be fixed by changing https://docs.python-requests.org to https://requests.readthedocs.io, I don't know if there's a precedent on how to handle this? Maybe just wait a few hours. I'm following upstream's issue.

[nateprewitt]

@JulienPalard I'd advise moving the domain to https://requests.readthedocs.io if that's acceptable. That will be the primary domain going forward as there isn't a clear path to Kenneth retrieving the python-requests.org domain.

[AA-Turner]

Thanks Nate, we went ahead and did this in #10484. Thanks for confirming https://requests.readthedocs.io/ will be the main domain going ahead.

A

[AA-Turner]

I closed & re-opened but just realised the fix won't be in this branch so it'll most likely fail again! Sorry for the noise.

A

[AA-Turner]

One note, looks good otherwise.

A

[tk0miya]

Looks good. Thank you for developing great tool!

[AA-Turner]

@JulienPalard it is failing on the below, which is valid reST (rendered). I think check_missing_space_after_literal needs to be updated to ignore [\-.,:;!?\\/'")]}>], see item 7 of the inline markup recognition rules.

   The version of Sphinx used to build represented as a tuple of five elements.
   For Sphinx version 3.5.1 beta 3 this would be ``(3, 5, 1, 'beta', 3)``.
   The fourth element can be one of: ``alpha``, ``beta``, ``rc``, ``final``.
   ``final`` always has 0 as the last element.

For now I will disable that check and merge if CI passes, as it is a good improvement.

A

[AA-Turner]

Thanks @JulienPalard!

A

[JulienPalard]

@JulienPalard it is failing on the below, which is valid reST (rendered).

Can't reproduce:

#10573