Create separate venv for docs and upgrade sphinx packages to latest versions.

Author: runemalm

.gitignore

@@ -72,3 +72,6 @@ docs/_build/
 # Project-specific files
 scratch
 env.make
+
+# Docs
+docs/.venv

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
+    python: "3.12.11"
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:

Makefile

@@ -12,6 +12,8 @@ SRC := $(PWD)/src
 TESTS := $(PWD)/tests
 DOCS := $(PWD)/docs
 
+DOCS_PYTHON_VERSION := 3.12.11
+
 # Load env file
 include env.make
 export $(shell sed 's/=.*//' env.make)
@@ -60,28 +62,44 @@ upload-test: ## upload package to testpypi repository
 upload: ## upload package to pypi repository
 	TWINE_USERNAME=$(PYPI_USERNAME) TWINE_PASSWORD=$(PYPI_PASSWORD) pipenv run twine upload --skip-existing dist/*
 
-.PHONY: sphinx-generate-requirements
-sphinx-generate-requirements: ## Export sphinx-related deps from Pipfile to docs/requirements.txt for Read the Docs
-	@echo "# Auto-generated for Read the Docs. Do not edit manually." > docs/requirements.txt
-	@grep -A 1000 '^\[dev-packages\]' Pipfile \
-		| grep '^sphinx' \
-		| sed 's/ *= */==/' \
-		| tr -d '"' \
-		>> docs/requirements.txt
+################################################################################
+# DOCS
+################################################################################
+
+.PHONY: sphinx-venv-init
+sphinx-venv-init: ## Init venv for docs (requires pyenv $(DOCS_PYTHON_VERSION))
+	cd $(DOCS) && \
+	command -v pyenv >/dev/null || { echo "pyenv not found"; exit 1; } && \
+	pyenv versions --bare | grep -q "^$(DOCS_PYTHON_VERSION)$$" || { echo "pyenv $(DOCS_PYTHON_VERSION) not installed"; exit 1; } && \
+	PYENV_PYTHON=$$(pyenv root)/versions/$(DOCS_PYTHON_VERSION)/bin/python && \
+	$$PYENV_PYTHON -m venv .venv && \
+	.venv/bin/pip install --upgrade pip && \
+	.venv/bin/pip install -r requirements.txt
+
+.PHONY: sphinx-venv-install
+sphinx-venv-install: ## Install or update docs venv from requirements.txt
+	cd $(DOCS) && \
+	[ -d .venv ] || { echo "Missing .venv — run sphinx-venv-init first."; exit 1; } && \
+	.venv/bin/pip install -r requirements.txt
+
+.PHONY: sphinx-venv-rm
+sphinx-venv-rm: ## Remove docs venv
+	rm -rf $(DOCS)/.venv
 
 .PHONY: sphinx-html
 sphinx-html: ## build the sphinx html
-	pipenv run make -C docs html
+	cd $(DOCS) && .venv/bin/sphinx-build -M html . _build
 
 .PHONY: sphinx-rebuild
 sphinx-rebuild: ## re-build the sphinx docs
 	cd $(DOCS) && \
-	pipenv run make clean && pipenv run make html
+	.venv/bin/sphinx-build -M clean . _build && \
+	.venv/bin/sphinx-build -M html . _build
 
 .PHONY: sphinx-autobuild
 sphinx-autobuild: ## activate autobuild of docs
 	cd $(DOCS) && \
-	pipenv run sphinx-autobuild . _build/html --watch $(SRC)
+	.venv/bin/sphinx-autobuild . _build/html --watch $(SRC)
 
 ################################################################################
 # PRE-COMMIT HOOKS
@@ -115,16 +133,16 @@ pre-commit-run: ## run the pre-commit hooks
 pipenv-rm: ## remove the virtual environment
 	pipenv --rm
 
-.PHONY: pipenv-install
-pipenv-install: ## setup the virtual environment
+.PHONY: pipenv-install-dev
+pipenv-install-dev: ## setup the virtual environment, with dev packages
 	pipenv install --dev
 
 .PHONY: pipenv-install-package
 pipenv-install-package: ## install a package (uses PACKAGE)
 	pipenv install $(PACKAGE)
 
-.PHONY: pipenv-install-package-dev
-pipenv-install-package-dev: ## install a dev package (uses PACKAGE)
+.PHONY: pipenv-install-dev-package
+pipenv-install-dev-package: ## install a dev package (uses PACKAGE)
 	pipenv install --dev $(PACKAGE)
 
 .PHONY: pipenv-graph

Pipfile

@@ -12,11 +12,8 @@ importlib-metadata = "==4.13.0"
 pre-commit = "*"
 pytest = "7.4.4"
 pytest-xdist = "*"
-sphinx = "5.3.0"
-sphinx-rtd-theme = "2.0.0"
-sphinx-autobuild = "2021.3.14"
-wheel = "0.41.2"
 typing-extensions = "*"
+wheel = "0.41.2"
 
 [requires]
 python_version = "3.7.17"