# Minimal makefile for Sphinx documentation
#

export PYVISTA_OFF_SCREEN := True

# You can set these variables from the command line.
SPHINXOPTS    =
DEFAULTS	  = -w sphinx_warnings.txt -W --keep-going
SPHINXBUILD   ?= uv run python -msphinx
SPHINXPROJ    = pyvista
SOURCEDIR     = source
BUILDDIR      = _build


.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

# Put it first so that "make" without argument is like "make help".
help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(DEFAULTS) $(O)

# `all` and `test` are POSIX conventions aliased to the CI-parity targets.
all: ci-build
test: ci-test

clean-dataset-gallery:
	rm -rf "$(SOURCEDIR)/api/examples/dataset-gallery"

clean-external-examples:
	rm -f $(SOURCEDIR)/getting-started/external_examples.rst

# remove autosummary files
clean-autosummary:
	find $(SOURCEDIR) -type d -name "_autosummary" -exec rm -rf {} +

clean-except-examples: clean-dataset-gallery clean-external-examples clean-autosummary
	rm -rf $(BUILDDIR)/*
	rm -f errors.txt
	rm -f sphinx_warnings.txt
	rm -rf $(SOURCEDIR)/images/auto-generated
	rm -rf $(SOURCEDIR)/tags

clean: clean-except-examples
	rm -rf $(SOURCEDIR)/examples/

# build html docs in parallel using all available CPUs
# WARNING: this is a resource hog
phtml:
	$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(DEFAULTS) $(O) -j auto

# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(DEFAULTS) $(O)

update-intersphinx:
	cd intersphinx && ./update.sh

gen-dataset-gallery:
	@if [ ! -d "$(SOURCEDIR)/api/examples/dataset-gallery" ]; then \
		echo "Dataset gallery directory not found, running make_table.py..."; \
		mkdir -p "$(SOURCEDIR)/api/examples/dataset-gallery"; \
		cd "$(SOURCEDIR)" && uv run python make_tables.py; \
	else \
		echo "Dataset gallery directory already exists, skipping generation."; \
		echo "Run clean-dataset-gallery to clear the gallery."; \
	fi

gen-external-examples:
	@if [ ! -f "$(SOURCEDIR)/getting-started/external_examples.rst" ]; then \
		echo "external_examples.rst not found, running make_external_examples.py..."; \
		cd "$(SOURCEDIR)" && uv run python make_external_gallery.py; \
	else \
		echo "The file external_examples.rst already exists, skipping generation."; \
		echo "Run clean-external-examples to clear the file."; \
	fi

# Spin up a local http server to view the rendered documentation.
# This is required for interactive examples to work.
serve-html:
	uv run python -m http.server 11000 --directory "$(BUILDDIR)"/html

# Full CI-parity documentation build via tox. Delegates to the `docs-build`
# tox env defined in ../tox.ini, which handles the gen steps and runs
# sphinx with the exact same flags as CI. Equivalent to `make docs` from
# the repo root.
ci-build:
	@echo "Building documentation via tox (matches CI)"
	@cd .. && uv run tox -e docs-build -- $(ARGS)

# Test the built documentation via tox (matches CI `tox -e docs-test`).
# Requires a prior successful `make ci-build` (or `make docs` at the root).
ci-test:
	@echo "Testing built documentation via tox (matches CI)"
	@cd .. && uv run tox -e docs-test -- $(ARGS)
