docs: migrate to the tprocv2-era documentation tree

.gitignore

@@ -32,13 +32,16 @@ __pycache__/
 .installed.cfg
 *.egg
 
+# Docs build venv (see docs/requirements.txt, docs/Makefile)
+/.venv/
+
 # Distribution / packaging
 build/
 dist/
 
 # Sphinx documentation
-docs/_build/
-docs/_autosummary/
+docs/source/_build/
+docs/source/_autosummary/
 
 ### macOS template
 # General

.readthedocs.yaml

@@ -9,10 +9,12 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.7"
+  apt_packages:
+    - pandoc  # required by nbsphinx to render the tutorial notebooks
 
-# Build documentation in the docs/ directory with Sphinx
+# Build documentation in the docs/source/ directory with Sphinx
 sphinx:
-  configuration: docs/conf.py
+  configuration: docs/source/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: []

docs/Makefile

@@ -3,7 +3,10 @@
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+# Defaults to the project venv (../.venv, see docs/requirements.txt) if it
+# exists, so 'make html' works without manually activating it first.
+# Override with 'make SPHINXBUILD=... html' to use a different interpreter/env.
+SPHINXBUILD   = $(if $(wildcard ../.venv/bin/sphinx-build),../.venv/bin/sphinx-build,sphinx-build)
 PAPER         =
 BUILDDIR      = _build
 
@@ -15,9 +18,9 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 # the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
 
@@ -85,11 +88,11 @@ htmlhelp:
 qthelp:
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	@echo "Build finished; now you can run \"qcollectiongenerator\" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/SphinxApidocTurorial.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/project_name.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/SphinxApidocTurorial.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/project_name.qhc"
 
 applehelp:
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@@ -104,8 +107,8 @@ devhelp:
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/SphinxApidocTurorial"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/SphinxApidocTurorial"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/project_name"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/project_name"
 	@echo "# devhelp"
 
 epub:
@@ -130,7 +133,7 @@ latexpdfja:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through platex and dvipdfmx..."
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+	@echo "platex/dvipdfmx finished; the PDF files are in $(BUILDDIR)/latex."
 
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text