Make docs build offline

Author: rartino

Makefile

@@ -4,7 +4,7 @@ PYTHON ?= python3
 # between httk repositories (read by docs/conf.py via HTTK_DOCS_BASE_URL).
 DOCS_BASE_URL ?= https://docs.httk.org
 
-.PHONY: docs docs-live docs-clean clean
+.PHONY: docs docs-live docs-clean docs-inventories clean
 
 docs: docs-clean
 	HTTK_DOCS_BASE_URL=$(DOCS_BASE_URL) $(PYTHON) -m sphinx -E -a -b html -W --keep-going docs docs/_build/html
@@ -13,7 +13,12 @@ docs-live:
 	HTTK_DOCS_BASE_URL=$(DOCS_BASE_URL) sphinx-autobuild docs docs/_build/html
 
 docs-clean:
-	rm -rf docs/_build
+	rm -rf docs/_build docs/reference/autoapi
+
+# Refresh the committed intersphinx inventories (the one docs task that uses the
+# network); docs builds themselves resolve against these vendored files offline.
+docs-inventories:
+	curl -fsSL https://docs.python.org/3/objects.inv -o docs/_inventories/python.inv
 
 clean: docs-clean
 	find . -name "*.pyc" -print0 | xargs -0 rm -f

docs/_inventories/python.inv

@@ -97,8 +97,11 @@
 # working.
 _docs_base_url = os.environ.get("HTTK_DOCS_BASE_URL", "https://docs.httk.org")
 
+# The inventory is vendored in docs/_inventories/ so docs builds need no network
+# access; link targets still point at the live site. Refresh the committed
+# inventory with `make docs-inventories`.
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
+    "python": ("https://docs.python.org/3", "_inventories/python.inv"),
 }
 
 # Plain "go to the module's docs" links, e.g. {moduledocs}`httk-core`.