docs: add devenv and linkcheck

.gitpod.yml

@@ -2,9 +2,9 @@ tasks:
   - init: |
       pip3 install sphinx-autobuild
       pip3 install -r docs/requirements.txt
-      pip3 install -e.
+      pip3 install -e .
     command: |
-      sphinx-autobuild docs/source/ docs/build/html/
+      sphinx-autobuild docs/source/ docs/_build/html/
     name: Sphinx preview
 ports:
-- port: 8000
+  - port: 8000

docs/Makefile

@@ -1,20 +1,38 @@
-# Minimal makefile for Sphinx documentation
-#
+# Makefile for Sphinx documentation generated by sphinx-quickstart
+# ----------------------------------------------------------------------------
 
-# You can set these variables from the command line.
-SPHINXOPTS    = -W
-SPHINXBUILD   = python3 -msphinx
-SPHINXPROJ    = repo2docker
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# "make mode" option.
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+
+# Manually added commands
+# ----------------------------------------------------------------------------
+
+# For local development:
+# - builds and rebuilds html on changes to source
+# - starts a livereload enabled webserver and opens up a browser
+devenv:
+	sphinx-autobuild -b html --open-browser "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+# For local development and CI:
+# - verifies that links are valid
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."

docs/make.bat

@@ -5,32 +5,51 @@ pushd %~dp0
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python -msphinx
+	set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
-set BUILDDIR=build
-set SPHINXPROJ=repo2docker
+set BUILDDIR=_build
 
 if "%1" == "" goto help
+if "%1" == "devenv" goto devenv
+if "%1" == "linkcheck" goto linkcheck
+goto default
 
+
+:default
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
-	echo.The Sphinx module was not found. Make sure you have Sphinx installed,
-	echo.then set the SPHINXBUILD environment variable to point to the full
-	echo.path of the 'sphinx-build' executable. Alternatively you may add the
-	echo.Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.The 'sphinx-build' command was not found. Open and read README.md!
 	exit /b 1
 )
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
 goto end
 
+
 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M help "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:devenv
+sphinx-autobuild >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-autobuild' command was not found. Open and read README.md!
+	exit /b 1
+)
+sphinx-autobuild -b html --open-browser "%SOURCEDIR%" "%BUILDDIR%/html" %SPHINXOPTS%
+goto end
+
+
+:linkcheck
+%SPHINXBUILD% -b linkcheck "%SOURCEDIR%" "%BUILDDIR%/linkcheck" %SPHINXOPTS%
+echo.
+echo.Link check complete; look for any errors in the above output 
+echo.or in "%BUILDDIR%/linkcheck/output.txt".
+goto end
+
 
 :end
 popd

docs/requirements.txt

@@ -2,3 +2,4 @@ sphinx==4.0.2
 sphinxcontrib-autoprogram==0.1.7
 pydata-sphinx-theme==0.6.3
 myst-parser==0.15.2
+sphinx-autobuild

docs/source/contributing/contributing.md

@@ -184,13 +184,11 @@ Then you are good to go!
 
 ## Building the documentation locally
 
-If you only changed the documentation, you can also build the documentation locally using `sphinx` .
+You can build and inspect the result of documentation changes locally.
 
 ```bash
 pip install -r docs/requirements.txt
 
 cd docs/
-make html
+make devenv
 ```
-
-Then open the file `docs/build/html/index.html` in your browser.