Update documentation related settings

.github/workflows/checks.yaml

@@ -9,7 +9,7 @@ on:
 
 env:
   # Also change CACHE_VERSION in the other workflows
-  CACHE_VERSION: 5
+  CACHE_VERSION: 6
   DEFAULT_PYTHON: 3.8
   PRE_COMMIT_CACHE: ~/.cache/pre-commit
 
@@ -58,6 +58,7 @@ jobs:
           . venv/bin/activate
           python -m pip install -U pip setuptools wheel
           pip install -U -r requirements_test.txt
+          pip install -U -r doc/requirements.txt
       - name: Generate pre-commit restore key
         id: generate-pre-commit-key
         run: >-
@@ -155,7 +156,7 @@ jobs:
   documentation:
     name: documentation
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 10
     needs: prepare-base
     steps:
       - name: Check out code from GitHub
@@ -182,3 +183,8 @@ jobs:
         run: |
           . venv/bin/activate
           pytest doc/test_messages_documentation.py
+      - name: Check documentation build and links
+        run: |
+          . venv/bin/activate
+          cd doc
+          make html

.readthedocs.yaml

@@ -7,6 +7,10 @@ sphinx:
   configuration: doc/conf.py
 
 python:
-  version: 3.8
   install:
     - requirements: doc/requirements.txt
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.8"

doc/Makefile

@@ -13,9 +13,9 @@ PYTHONPATH    =
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees -T -E -W --keep-going $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest all
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -34,21 +34,21 @@ help:
 	@echo "  man        to make manual pages"
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
 	-rm -rf $(BUILDDIR)/*
-	-rm -f reference_guide/features.rst
-	-rm -f extensions.rst
 
-html: features.rst extensions.rst
+html:
 	@echo
 	@echo "Install dependencies"
-	$(PIP) install python-docs-theme
+	$(PIP) install furo
 	@echo "Finished installing dependencies"
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -132,22 +132,3 @@ linkcheck:
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-
-extensions.rst: exts/pylint_extensions.py
-extensions.rst: $(shell find ../pylint/extensions -type f -regex '.*\.py')
-extensions.rst: $(shell find ../pylint/extensions -type f -regex '.*\.rst')
-	rm -f extensions.rst
-	PYTHONPATH=$(PYTHONPATH) $(PYTHON) ./exts/pylint_extensions.py
-
-features.rst: exts/pylint_features.py
-features.rst: $(shell find ../pylint/checkers -type f -regex '.*\.py')
-	rm -f features.rst
-	PYTHONPATH=$(PYTHONPATH) $(PYTHON) ./exts/pylint_features.py
-
-messages: $(PYTHONPATH) $(PYTHON) ./exts/pylint_messages.py

doc/make.bat

@@ -6,11 +6,9 @@ if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
 set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-set I18NSPHINXOPTS=%SPHINXOPTS% .
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees -T -E -W --keep-going .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
 )
 
 if "%1" == "" goto help
@@ -34,7 +32,6 @@ if "%1" == "help" (
 	echo.  gettext    to make PO message catalogs
 	echo.  changes    to make an overview over all changed/added/deprecated items
 	echo.  linkcheck  to check all external links for integrity
-	echo.  doctest    to run all doctests embedded in the documentation if enabled
 	goto end
 )
 
@@ -46,17 +43,13 @@ if "%1" == "clean" (
 
 
 if "%1" == "html" (
-	rm -f features.rst
-	echo Pylint features > reference_guide/features.rst
-	echo =============== >> reference_guide/features.rst
-	echo  >> reference_guide/features.rst
-	echo .. generated by pylint --full-documentation >> reference_guide/features.rst
-	echo  >> reference_guide/features.rst
-	python -m pylint --full-documentation >> reference_guide/features.rst
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
 	if errorlevel 1 exit /b 1
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
 	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
 	goto end
 )
 
@@ -162,7 +155,7 @@ if "%1" == "texinfo" (
 )
 
 if "%1" == "gettext" (
-	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	%SPHINXBUILD% -b gettext %ALLSPHINXOPTS% %BUILDDIR%/locale
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
@@ -186,13 +179,4 @@ or in %BUILDDIR%/linkcheck/output.txt.
 	goto end
 )
 
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	if errorlevel 1 exit /b 1
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
 :end