clamsproject · keighrim · Nov 30, 2025 · Nov 20, 2025 · Nov 29, 2025 · Nov 29, 2025
diff --git a/.gitignore b/.gitignore
@@ -77,11 +77,7 @@ mmif/vocabulary
 ./VERSION*
 .hypothesis
 
-
-# sphinx/autodoc files
-documentation/_build/
-
-/VERSION
-_issues
-
+# Documentation build artifacts
 documentation/cli_help.rst
+documentation/whatsnew.rst
+docs-test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,47 @@
+# Contributing to mmif-python
+
+## Documentation
+
+The documentation for `mmif-python` is built using Sphinx and published to the [CLAMS documentation hub](https://github.com/clamsproject/website-test).
+
+### Building Documentation Locally
+
+To build the documentation for the current checkout:
+
+```bash
+make doc
+# OR
+python3 build-tools/docs.py
+```
+
+The output will be in `documentation/_build/html`.
+
+### Building Documentation for Old Versions
+
+To build documentation for a specific historical version (e.g., `v1.0.0`):
+
+```bash
+make doc-version
+# OR
+python3 build-tools/docs.py --build-ver v1.0.0
+```
+
+This runs the build in a sandboxed temporary directory. The output will be in `docs-test/<version>`.
+
+### Troubleshooting Old Version Builds
+
+**Important:** The build script (`build-tools/docs.py`) uses a "Modern Environment, Legacy Source" strategy. It checks out the old source code but installs **modern** build dependencies (Sphinx 7.x, Furo) to ensure the build works on current systems (including Python 3.13).
+
+If an old version fails to build because a dependency is missing (e.g., it was removed from `requirements.txt` in later versions but the old `setup.py` needs it), **do not try to fix the old `setup.py`**.
+
+Instead, manually add the missing dependency to the `run_pip` call in `build-tools/docs.py`:
+
+```python
+# In build-tools/docs.py
+def build_versioned_docs(...):
+    # ...
+    # Add the missing dependency here
+    env.run_pip("install", "jsonschema", "requests", "pyyaml", "deepdiff<7", "YOUR_MISSING_DEP", cwd=source_path)
+```
+
+This "overlay" strategy ensures we can build old docs without modifying historical git tags.
diff --git a/Makefile b/Makefile
@@ -35,19 +35,18 @@ publish: distclean version package test
 
 $(generatedcode): dist/$(sdistname)*.tar.gz
 
-docs: latest := $(shell git tag | sort -t. -k 1,1nr -k 2,2nr -k 3,3nr -k 4,4nr | head -n 1)
-docs: VERSION $(generatedcode)
-	rm -rf docs
-	pip install --upgrade -r requirements.txt
-	pip install --upgrade -r requirements.old
-	sphinx-multiversion documentation docs -b html -a
-	touch docs/.nojekyll
-	ln -sf $(latest) docs/latest
-	echo "<!DOCTYPE html> <html> <head> <title>Redirect to latest version</title> <meta charset=\"utf-8\"> <meta http-equiv=\"refresh\" content=\"0; url=./latest/index.html\"> </head> </html>" > docs/index.html
-
-doc: VERSION $(generatedcode) # for single version sphinx - only use when developing
-	rm -rf docs
-	sphinx-build documentation docs -b html -a
+docs:
+	@echo "WARNING: The 'docs' target is deprecated and will be removed."
+	@echo "The 'docs' directory is no longer used. Documentation is now hosted in the central CLAMS documentation hub."
+	@echo "Use 'make doc' for local builds or 'make doc-version' for specific versions."
+	@echo "Nothing is done."
+
+doc: # for single version sphinx - builds current source
+	python3 build-tools/docs.py
+
+doc-version: # interactive build for specific version
+	@read -p "Enter version/tag to build (e.g., v1.0.0): " ver; \
+	[ -n "$$ver" ] && python3 build-tools/docs.py --build-ver $$ver
 
 package: VERSION dist/$(sdistname)*.tar.gz
 

diff --git a/README.md b/README.md
@@ -16,3 +16,6 @@ including ;
 * [Version history and patch notes](https://github.com/clamsproject/mmif-python/blob/main/CHANGELOG.md)
 * [MMIF Python API documentation](https://clamsproject.github.io/mmif-python)
 * [MMIF JSON specification and schema](https://clamsproject.github.io/mmif)
+
+## For devs ...
+* Build documentation: `python build-tools/docs.py --help`