docs maintenance: add devenv and linkcheck to Makefile and misc details

.readthedocs.yml

@@ -1,24 +1,17 @@
 # Configuration on how ReadTheDocs (RTD) builds our documentation
+# ref: https://readthedocs.org/projects/binderhub/
 # ref: https://docs.readthedocs.io/en/stable/config-file/v2.html
-
-# Required (RTD configuration version)
+#
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
-  configuration: doc/conf.py
+  configuration: docs/conf.py
 
-# Optionally build your docs in additional formats such as PDF and ePub
-formats: []
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
-  version: 3.7
   install:
-    # WARNING: This requirements file will be installed without the pip
-    #          --upgrade flag in an existing environment. This means that if a
-    #          package is specified without a lower boundary, we may end up
-    #          accepting the existing version.
-    #
-    #          ref: https://github.com/readthedocs/readthedocs.org/blob/0e3df509e7810e46603be47d268273c596e68455/readthedocs/doc_builder/python_environments.py#L335-L344
-    - requirements: doc/doc-requirements.txt
+    - requirements: doc/requirements.txt

CONTRIBUTING.md

@@ -32,7 +32,7 @@ language](http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
 1. Install BinderHub and the documentation tools:
 
    ```bash
-   python3 -m pip install -r doc/doc-requirements.txt
+   python3 -m pip install -r doc/requirements.txt
    ```
 
 1. The documentation is located in the `doc/` sub-directory, `cd` into it:

doc/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    = BinderHub
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -W
+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."

doc/make.bat

@@ -0,0 +1,58 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXOPTS%" == "" (
+	set SPHINXOPTS=-W
+)
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+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-build' command was not found. Open and read README.md!
+	exit /b 1
+)
+%SPHINXBUILD% -M %1 "%SOURCEDIR%" "%BUILDDIR%" %SPHINXOPTS%
+goto end
+
+
+:help
+%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

doc/requirements.txt

@@ -0,0 +1,12 @@
+# sphinx.ext.autodoc and autodoc_traits as configured to be used in conf.py is
+# automatically building documentation based on inspection of the binderhub
+# package, which means we need to install it on RTD so it is available for
+# inspection.
+-r ../requirements.txt
+
+# Documentation specific packages
+autodoc-traits
+myst-parser
+pydata-sphinx-theme
+sphinx-autobuild
+sphinx-copybutton