From 2ca490e5a58fb3e4610b2de5458250dad0a28b05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Wed, 13 Apr 2022 11:31:35 +0200 Subject: [PATCH 1/3] Don't use deprecated python version config for readthedocs --- .readthedocs.yaml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c0fb27844f..0fec8925dd 100644 --- a/.readthedocs.yaml +++ b/.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" From fe785109cf4a414b156a92a41fd1d405ef62d367 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Wed, 13 Apr 2022 12:20:14 +0200 Subject: [PATCH 2/3] Update Sphinx makefiles with options used on readthedocs --- doc/Makefile | 35 ++++++++--------------------------- doc/make.bat | 28 ++++++---------------------- 2 files changed, 14 insertions(+), 49 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 278eea8977..be90a2dfd3 100644 --- a/doc/Makefile +++ b/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 ' where 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 diff --git a/doc/make.bat b/doc/make.bat index 7c754602b5..64127d62a8 100644 --- a/doc/make.bat +++ b/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 From d66d258baed826c277ce3bba8ac43f0b6aad7f8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dani=C3=ABl=20van=20Noord?= <13665637+DanielNoord@users.noreply.github.com> Date: Wed, 13 Apr 2022 12:20:31 +0200 Subject: [PATCH 3/3] Add CI check for building of documentation and linkcheck --- .github/workflows/checks.yaml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index a505032319..cef113bf30 100644 --- a/.github/workflows/checks.yaml +++ b/.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