# Makefile for Sphinx documentation.
#
#     make -C docs html      build the documentation into docs/_build/html
#     make -C docs clean     remove the build output and the generated timing tables
#
# SOURCEDIR must stay in step with .readthedocs.yaml, which points Sphinx at
# docs/source/conf.py. sphinx-gallery resolves examples_dirs against the source
# directory, so building from docs/ instead sends "../examples" outside the repository
# and the build fails before it starts.
#
# docs/source/auto_examples and auto_tutorials are sphinx-gallery's cache, not build
# output. They are gitignored, which makes them look disposable, but sphinx-gallery
# md5-hashes each script and re-runs only the ones that changed: an unchanged rebuild
# takes seconds, while deleting them forces every example to execute again, which is tens
# of minutes. `clean` deliberately leaves them alone -- remove them by hand only when you
# want a genuinely cold build.

SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
CONFDIR = source
BUILDDIR = _build

# Generated by sphinx-gallery next to the pages they describe. `sphinx-build -M clean`
# only removes BUILDDIR, so these survive it and keep referencing examples that may no
# longer exist, which raises ref.ref warnings on the next build.
TIMING_TABLES = \
	$(SOURCEDIR)/sg_execution_times.rst \
	$(SOURCEDIR)/auto_examples/sg_execution_times.rst \
	$(SOURCEDIR)/auto_tutorials/sg_execution_times.rst

help:
	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(CONFDIR)" $(SPHINXOPTS) $(O)

clean:
	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(CONFDIR)" $(SPHINXOPTS) $(O)
	@rm -f $(TIMING_TABLES)

.PHONY: help clean Makefile

%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -c "$(CONFDIR)" $(SPHINXOPTS) $(O)
