mirror of
https://github.com/microsoft/mscclpp.git
synced 2026-05-11 17:00:22 +00:00
ed565ceb33
The v0.9.0 conf.py (introduced in #775) dynamically loads the version from python/mscclpp/_version.py. This file is generated at build time by setuptools_scm and is listed in .gitignore — it is never committed to the repo. Earlier tags (v0.8.0 and below) used a hardcoded release (e.g., "v0.8.0") in conf.py, so they had no dependency on generated files. sphinx-multiversion checks out each tag using git archive, which only extracts committed files. Since _version.py is not committed, the v0.9.0 checkout is missing it, and conf.py crashes on import. All future tags will have this same problem. **Three changes:** 1. docs/build_multiversion.py (new): A wrapper around sphinx-multiversion that monkey-patches copy_tree to generate _version.py in each tag checkout after extraction. The version string is parsed from the tag name (e.g., v0.9.0 → __version__ = "0.9.0"). 2. Makefile: The multiversion target now calls build_multiversion.py instead of sphinx-multiversion directly. 3. conf.py: Added a fallback so that if _version.py doesn't exist, it reads the version from the VERSION file instead. This makes conf.py resilient for any future scenario where _version.py is missing. **Testing** Verified locally: • make multiversion now successfully builds all 11 versions (v0.4.0 through v0.9.0) • v0.9.0 docs are correctly generated under _build/html/v0.9.0/ Version selector shows v0.9.0 as latest
51 lines
2.1 KiB
Makefile
51 lines
2.1 KiB
Makefile
# Minimal makefile for Sphinx documentation
|
|
#
|
|
|
|
# You can set these variables from the command line, and also
|
|
# from the environment for the first two.
|
|
SPHINXOPTS ?=
|
|
SPHINXBUILD ?= sphinx-build
|
|
SPHINXMULTIVERSION ?= python3 build_multiversion.py
|
|
SOURCEDIR = .
|
|
BUILDDIR = _build
|
|
|
|
# Put it first so that "make" without argument is like "make help".
|
|
help:
|
|
@echo "Usage:"
|
|
@echo " make html - Build single-version HTML (fast, for development)"
|
|
@echo " make multiversion - Build all versions with sphinx-multiversion"
|
|
@echo " make clean - Remove build directory"
|
|
@echo ""
|
|
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
|
|
.PHONY: help Makefile generate-versions multiversion clean
|
|
|
|
# Generate versions.js from git tags before building
|
|
generate-versions:
|
|
@python3 generate_versions.py
|
|
|
|
# Build all documentation versions using sphinx-multiversion
|
|
# NOTE: This target should only be run from the main branch to ensure
|
|
# the root docs correctly represent "main (dev)". For local development
|
|
# on feature branches, use "make html" instead.
|
|
# GitHub Actions workflow runs this on main branch only.
|
|
multiversion: generate-versions
|
|
@cd .. && python3 -m setuptools_scm --force-write-version-files
|
|
@export LC_ALL=C.UTF-8; $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
|
@echo "Building versioned docs from tags..."
|
|
@export LC_ALL=C.UTF-8; $(SPHINXMULTIVERSION) "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
|
|
@mkdir -p $(BUILDDIR)/html/_static
|
|
@cp -f _static/versions.js $(BUILDDIR)/html/_static/ 2>/dev/null || true
|
|
@cp -f _static/version-selector.js $(BUILDDIR)/html/_static/ 2>/dev/null || true
|
|
|
|
# Clean build directory
|
|
clean:
|
|
@rm -rf $(BUILDDIR)
|
|
|
|
# Catch-all target: route all unknown targets to Sphinx using the new
|
|
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
|
# This builds single-version only (fast for development).
|
|
%: Makefile generate-versions
|
|
@cd .. && python3 -m setuptools_scm --force-write-version-files
|
|
@export LC_ALL=C.UTF-8; $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|