From bb158cc4121c2868d164bc830d51589e53ba18ee Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.i.sundell@gmail.com>
Date: Wed, 27 Oct 2021 01:43:17 +0200
Subject: [PATCH] Modernize docs Makefile with sphinx-autobuild

---
 docs/Makefile         | 36 +++++++++++++++++++++++++++---------
 docs/requirements.txt |  1 +
 2 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/docs/Makefile b/docs/Makefile
index 5b24fa0..e74b054 100644
--- a/docs/Makefile
+++ b/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   = sphinx-build
-SPHINXPROJ    = TheLittlestJupyterHub
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= 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)
+	@$(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."
diff --git a/docs/requirements.txt b/docs/requirements.txt
index ed6543d..4bb009f 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,3 +1,4 @@
 sphinx>=1.4, !=1.5.4
+sphinx-autobuild
 sphinx_copybutton
 pydata-sphinx-theme