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]>

docs/Makefile

@@ -17,7 +17,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 +40,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 +155,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."

requirements-dev.txt

@@ -6,6 +6,7 @@ pyenchant==3.2.2
 pylint==2.17.2
 autopep8==1.6.0
 black==22.3.0
+sphinx==7.2.6
 
 coverage==5.5
 
@@ -24,7 +25,7 @@ xmlschema==1.7.0; python_version < '3.12'
 xmlschema==2.5.0; python_version >= '3.12'
 
 # For building the manpage
-docutils==0.17.1
+docutils==0.18.1
 
 # For tests that check content generated by runners
 jsonschema==3.2.0

selftests/doctest.sh

@@ -0,0 +1,7 @@
+#!/bin/sh -e
+
+(cd "./docs" && make -k check)
+
+exit $?
+
+