| 1 |
# Minimal makefile for Sphinx documentation |
| 2 |
# |
| 3 |
|
| 4 |
export PYVISTA_OFF_SCREEN := True |
| 5 |
|
| 6 |
# You can set these variables from the command line. |
| 7 |
SPHINXOPTS = |
| 8 |
DEFAULTS = -w sphinx_warnings.txt -W --keep-going |
| 9 |
SPHINXBUILD ?= uv run python -msphinx |
| 10 |
SPHINXPROJ = pyvista |
| 11 |
SOURCEDIR = source |
| 12 |
BUILDDIR = _build |
| 13 |
|
| 14 |
|
| 15 |
.PHONY: all help Makefile test clean clean-dataset-gallery clean-external-examples clean-autosummary clean-except-examples phtml update-intersphinx gen-dataset-gallery gen-external-examples serve-html ci-build ci-test |
| 16 |
|
| 17 |
# Put it first so that "make" without argument is like "make help". |
| 18 |
help: |
| 19 |
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(DEFAULTS) $(O) |
| 20 |
|
| 21 |
# `all` and `test` are POSIX conventions aliased to the CI-parity targets. |
| 22 |
all: ci-build |
| 23 |
test: ci-test |
| 24 |
|
| 25 |
clean-dataset-gallery: |
| 26 |
rm -rf "$(SOURCEDIR)/api/examples/dataset-gallery" |
| 27 |
|
| 28 |
clean-external-examples: |
| 29 |
rm -f $(SOURCEDIR)/getting-started/external_examples.rst |
| 30 |
|
| 31 |
# remove autosummary files |
| 32 |
clean-autosummary: |
| 33 |
find $(SOURCEDIR) -type d -name "_autosummary" -exec rm -rf {} + |
| 34 |
|
| 35 |
clean-except-examples: clean-dataset-gallery clean-external-examples clean-autosummary |
| 36 |
rm -rf $(BUILDDIR)/* |
| 37 |
rm -f errors.txt |
| 38 |
rm -f sphinx_warnings.txt |
| 39 |
rm -rf $(SOURCEDIR)/images/auto-generated |
| 40 |
rm -rf $(SOURCEDIR)/tags |
| 41 |
|
| 42 |
clean: clean-except-examples |
| 43 |
rm -rf $(SOURCEDIR)/examples/ |
| 44 |
|
| 45 |
# build html docs in parallel using all available CPUs |
| 46 |
# WARNING: this is a resource hog |
| 47 |
phtml: |
| 48 |
$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(DEFAULTS) $(O) -j auto |
| 49 |
|
| 50 |
# Catch-all target: route all unknown targets to Sphinx using the new |
| 51 |
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). |
| 52 |
%: Makefile |
| 53 |
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(DEFAULTS) $(O) |
| 54 |
|
| 55 |
update-intersphinx: |
| 56 |
cd intersphinx && ./update.sh |
| 57 |
|
| 58 |
gen-dataset-gallery: |
| 59 |
@if [ ! -d "$(SOURCEDIR)/api/examples/dataset-gallery" ]; then \ |
| 60 |
echo "Dataset gallery directory not found, running make_table.py..."; \ |
| 61 |
mkdir -p "$(SOURCEDIR)/api/examples/dataset-gallery"; \ |
| 62 |
cd "$(SOURCEDIR)" && uv run python make_tables.py; \ |
| 63 |
else \ |
| 64 |
echo "Dataset gallery directory already exists, skipping generation."; \ |
| 65 |
echo "Run clean-dataset-gallery to clear the gallery."; \ |
| 66 |
fi |
| 67 |
|
| 68 |
gen-external-examples: |
| 69 |
@if [ ! -f "$(SOURCEDIR)/getting-started/external_examples.rst" ]; then \ |
| 70 |
echo "external_examples.rst not found, running make_external_examples.py..."; \ |
| 71 |
cd "$(SOURCEDIR)" && uv run python make_external_gallery.py; \ |
| 72 |
else \ |
| 73 |
echo "The file external_examples.rst already exists, skipping generation."; \ |
| 74 |
echo "Run clean-external-examples to clear the file."; \ |
| 75 |
fi |
| 76 |
|
| 77 |
# Spin up a local http server to view the rendered documentation. |
| 78 |
# This is required for interactive examples to work. |
| 79 |
serve-html: |
| 80 |
uv run python -m http.server 11000 --directory "$(BUILDDIR)"/html |
| 81 |
|
| 82 |
# Full CI-parity documentation build via tox. Delegates to the `docs-build` |
| 83 |
# tox env defined in ../tox.ini, which handles the gen steps and runs |
| 84 |
# sphinx with the exact same flags as CI. Equivalent to `make docs` from |
| 85 |
# the repo root. |
| 86 |
ci-build: |
| 87 |
@echo "Building documentation via tox (matches CI)" |
| 88 |
@cd .. && uv run tox -e docs-build -- $(ARGS) |
| 89 |
|
| 90 |
# Test the built documentation via tox (matches CI `tox -e docs-test`). |
| 91 |
# Requires a prior successful `make ci-build` (or `make docs` at the root). |
| 92 |
ci-test: |
| 93 |
@echo "Testing built documentation via tox (matches CI)" |
| 94 |
@cd .. && uv run tox -e docs-test -- $(ARGS) |