Improve Sphinx building and linting

Run sphinx-builder with -W (fail on error), --keep-going, and -j auto.
Auto-job scaling speeds up sphinx-builder a LOT.

Add make lint target to doc/Makefile. The -E and -a option ensure that
all files are always re-read and rewritten.

Add option to run sphinx-builder from a virtual env that mimics RTD
builds closer than Fedora packages.

Signed-off-by: Christian Heimes <cheimes@redhat.com>
Reviewed-By: François Cami <fcami@redhat.com>

.gitignore

@@ -86,6 +86,7 @@ freeipa2-dev-doc
 /daemons/test-driver
 
 /doc/_build
+/doc/.venv
 !/doc/Makefile
 
 /po/test.po

Makefile.am

@@ -103,6 +103,7 @@ clean-local:
 	rm -f "$(top_builddir)"/$(PACKAGE)-*.tar.gz
 	rm -rf "$(top_srcdir)/cov-int"
 	rm -f "$(top_srcdir)/freeipa.tgz"
+	$(MAKE) -C "$(top_srcdir)/doc" distclean
 
 # convenience targets for RPM build
 .PHONY: rpmroot rpmdistdir version-update _dist-version-bakein _rpms-prep \
@@ -331,10 +332,9 @@ yamllint:
 #
 .PHONY: doclint
 doclint:
-	@echo -e "\nBuild and lint documentation";
-	@echo "-----------";
-	@$(MAKE) -C $(srcdir)/doc/ clean;
-	@$(MAKE) -C $(srcdir)/doc/ html; 
+	@echo -e "\nBuild and lint documentation"
+	@echo "-----------"
+	$(MAKE) -C $(top_srcdir)/doc/ lint
 	@echo "-----------"
 
 # Run pylint for all python files. Finds all python files/packages, skips

doc/Makefile

@@ -3,14 +3,18 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -W
-SPHINXBUILD   ?= sphinx-build
+PYTHON        ?= python3
+VENVDIR       = ./.venv
+SPHINXOPTS    ?= -W --keep-going -j auto
+SPHINXBUILD   ?= PATH=$(VENVDIR)/bin:$$PATH sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "  lint        to check and lint documentation"
+	@echo "  venv        to create an isolated venv"
 
 .PHONY: help Makefile
 
@@ -24,3 +28,17 @@ workshop-remote:
 	git remote add -f freeipa-workshop https://github.com/freeipa/freeipa-workshop.git
 workshop-pull:
 	git pull -s subtree freeipa-workshop master
+
+.PHONY: lint
+lint:
+	$(MAKE) html SPHINXOPTS="$(SPHINXOPTS) -E -a"
+
+.PHONY: distclean
+distclean: clean
+	rm -rf $(VENVDIR)
+
+.PHONY: venv
+venv:
+	$(PYTHON) -m venv $(VENVDIR)
+	$(VENVDIR)/bin/python3 -m pip install -U pip setuptools
+	$(VENVDIR)/bin/python3 -m pip install -U -r ./requirements.txt

doc/conf.py

@@ -55,7 +55,9 @@ language = 'en'
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'workshop/README.rst']
+exclude_patterns = [
+    '_build', 'Thumbs.db', '.DS_Store', 'workshop/README.rst', '.venv/*'
+]
 
 
 # -- Options for HTML output -------------------------------------------------

doc/requirements.txt

@@ -1,3 +1,6 @@
+# m2r is not compatible with Sphinx 3.x
+sphinx < 3.0
+
 # convert markdown to rest
 m2r