Static checks for html documentation

This commit introduces the static checks for avocado documentation. This change will help us avoid documentation issues in the future. Reference: avocado-framework#5757 Signed-off-by: Jan Richter <[email protected]>
richtja · Dec 1, 2023 · 3754351 · 3754351
1 parent 093145e
commit 3754351
Show file tree

Hide file tree

Showing 3 changed files with 15 additions and 5 deletions.
diff --git a/docs/Makefile b/docs/Makefile
@@ -1,8 +1,6 @@
 # Makefile for Sphinx documentation
 #
-ifndef PYTHON
-PYTHON=$(shell which python3 2>/dev/null || which python 2>/dev/null)
-endif
+include ../Makefile.include
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
@@ -17,7 +15,7 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) sou
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext check
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -40,12 +38,13 @@ help:
 	@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)"
+	@echo "  check      to check HTML generation"
 
 clean:
 	-rm -rf $(BUILDDIR)
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	$(SPHINXBUILD) -W --keep-going -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
@@ -154,3 +153,6 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+check: html clean
+	@echo "Testing of html in the sources finished."
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -6,6 +6,7 @@ pyenchant==3.2.2
 pylint==2.17.2
 autopep8==1.6.0
 black==22.3.0
+sphinx==5.3.0
 
 coverage==5.5
 

diff --git a/selftests/doctest.sh b/selftests/doctest.sh
@@ -0,0 +1,7 @@
+#!/bin/sh -e
+
+(cd "./docs" && python3 -m sphinx -W --keep-going -b html -d build/doctrees   source build/html)
+
+exit $?
+
+