Debian Codegraph @

doc/Makefile

raw
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)