docs / tox: Build documentation to check for errors

Signed-off-by: Bernhard Kaindl <[email protected]>

Author: bernhardkaindl

.pre-commit-config.yaml

@@ -102,7 +102,7 @@ repos:
         name: pytest unit tests and static analysis using tox
         types: [python]
         # entry: sh -c "pytest -x -rf --new-first --show-capture=all >/dev/tty"
-        entry: sh -c "tox -e py311-cov-check-pytype-pyright-lint-mdreport >/dev/tty"
+        entry: sh -c "tox -e py311-cov-check-pytype-pyright-lint-docs-mdreport >/dev/tty"
         verbose: true
         language: python
         require_serial: true

docs/Makefile

@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -55,4 +55,5 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "furo"
-html_static_path = ["_static"]
+# No static html source files for now.
+# html_static_path = ["_static"]

tox.ini

@@ -12,7 +12,7 @@ min_version = 4.6
 # .github/workflows/main.yml is set up to test with 3.11, 3.12 and 3.13 in parallel.
 # Therefore, use three environments: One with 3.11, one with 3.12 and one with 3.13:
 #
-envlist = py311-covcp-check-pytype-mdreport, py312-cov, py313-cov-lint-pyright
+envlist = py311-covcp-check-pytype-mdreport, py312-cov-docs, py313-cov-lint-pyright
 isolated_build = true
 skip_missing_interpreters = true
 requires =
@@ -37,6 +37,7 @@ commands    =
 description = Run in a {basepython} virtualenv:
     cov:        {[cov]description}
     covcp:      Copy the generated .converage and coverage.xml to the UPLOAD_DIR dir
+    docs:       {[docs]description}
     fox:        {[fox]description}
     lint:       {[lint]description}
     mdreport:   Make a test report (which is shown in the GitHub Actions Summary Page)
@@ -56,12 +57,14 @@ deps =
     {cov,covcp,fox}: coverage[toml]
     {cov,covcp,fox}: diff-cover
     {lint,fox}: {[lint]deps}
+    docs: {[docs]deps}
     pyright: pyright
 allowlist_externals =
     {cov,covcp,fox,check,lint,test,mdreport}: echo
     {cov,covcp,fox,check,lint,test,mdreport}: sh
     {cov,covcp,fox}: cp
     check: cat
+    docs: make
     fox: firefox
 passenv =
     {pytype,lint,test}: GITHUB_STEP_SUMMARY
@@ -99,6 +102,7 @@ setenv =
     lint: ENVLOGDIR={envlogdir}
     {[cov]setenv}
 commands =
+    docs: {[docs]commands}
     lint: {[lint]commands}
     pyright: {[pyright]commands}
     check: {[check]commands}
@@ -126,6 +130,13 @@ commands    =
       --html-report  {envlogdir}/coverage-diff.html                                   \
                      {envlogdir}/coverage.xml
 
+
+[docs]
+description = Build the documentation to check for errors
+deps = -r docs/requirements.txt
+commands = make -C docs html SPHINXOPTS="--fail-on-warning"
+
+
 [lint]
 description = Run pylint and fail on warnings remaining on lines in the diff to master
 deps = pylint