Makefile

.PHONY: clean clean-gallery clean-prep clean-full spellcheck

SPHINXOPTS =

# Gallery path must be given relative to the docs/ folder

ifeq ($(GALLERY_PATH),)
GALLERY_PATH := ../../napari/examples
endif

mkfile_path := $(abspath $(lastword $(MAKEFILE_LIST)))
current_dir := $(dir $(mkfile_path))
docs_dir := $(current_dir)docs

clean:
	echo clean
	echo $(current_dir)
ifeq ($(OS),Windows_NT)
	@python -c "import shutil, pathlib, glob; shutil.rmtree('$(docs_dir)/_build', ignore_errors=True); [pathlib.Path(f).unlink(missing_ok=True) for f in glob.glob('$(docs_dir)/api/napari*.rst')]"
else
	rm -rf $(docs_dir)/_build/
	rm -rf $(docs_dir)/api/napari*.rst
endif

clean-prep: clean
ifeq ($(OS),Windows_NT)
	@python -c "import pathlib, glob; pathlib.Path('$(docs_dir)/guides/preferences.md').unlink(missing_ok=True); [pathlib.Path(f).unlink(missing_ok=True) for f in glob.glob('$(docs_dir)/developers/architecture/ui_sections/*ui.md')]; [pathlib.Path(f).unlink(missing_ok=True) for f in glob.glob('$(docs_dir)/plugins/_npe2*.md')]"
else
	rm -rf $(docs_dir)/guides/preferences.md
	rm -rf $(docs_dir)/developers/architecture/ui_sections/*ui.md
	rm -rf $(docs_dir)/plugins/_npe2*.md
endif

clean-gallery:
ifeq ($(OS),Windows_NT)
	@python -c "import shutil, pathlib; [pathlib.Path(f).unlink(missing_ok=True) for f in pathlib.Path('$(docs_dir)/gallery').glob('*') if f.is_file()]; shutil.rmtree('$(docs_dir)/_tags', ignore_errors=True)"
else
	rm -rf $(docs_dir)/gallery/*
	rm -rf $(docs_dir)/_tags
endif

clean-full: clean-prep clean-gallery

prep-docs:
	python $(docs_dir)/_scripts/prep_docs.py

# generate stubs in place of the files from prep_docs
# this will not overwrite existing files
prep-stubs:
	python $(docs_dir)/_scripts/prep_docs.py --stubs

docs-build: prep-docs
ifeq ($(OS),Windows_NT)
	set NAPARI_CONFIG=&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build  -WT --keep-going -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
else
	NAPARI_CONFIG="" NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -M html docs/ docs/_build  -WT --keep-going -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
endif

# build docs with xvfb (headless X server)
docs-xvfb: prep-docs
ifeq ($(OS),Windows_NT)
	@echo "xvfb is not supported on Windows. Use 'make html' or 'make docs-build' instead."
	@exit 1
else
	NAPARI_CONFIG="" NAPARI_APPLICATION_IPY_INTERACTIVE=0 xvfb-run --auto-servernum sphinx-build -M html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
endif

# build docs with xwfb (headless X server with Wayland support)
docs-xwfb: prep-docs
ifeq ($(OS),Windows_NT)
	@echo "xwfb is not supported on Windows. Use 'make html' or 'make docs-build' instead."
	@exit 1
else
	NAPARI_CONFIG="" NAPARI_APPLICATION_IPY_INTERACTIVE=0 xwfb-run -- sphinx-build -M html docs/ docs/_build -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
endif

# full docs (re)build
# cleans everything, starts from scratch
html: clean clean-gallery docs-build

# no gallery, no clean - call 'make clean' manually if needed
# will use stubs for autogenerated content if needed
# no initial build, so run a manual full or slim build first
# will rebuild notebooks and run cells in edited files
# autogenerated paths need to be ignored to prevent reload loops
html-noplot-live: prep-stubs
ifeq ($(OS),Windows_NT)
	set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-autobuild -b html docs/ docs/_build/html -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) --ignore $(docs_dir)"/_tags/*" --ignore $(docs_dir)"/api/napari*.rst" --ignore $(docs_dir)"/gallery/*" --ignore $(docs_dir)"/jupyter_execute/*" --open-browser --port=0 $(SPHINXOPTS)
else
	NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
	sphinx-autobuild \
		-b html \
		docs/ \
		docs/_build/html \
		-D plot_gallery=0 \
		-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
		--ignore $(docs_dir)"/_tags/*" \
		--ignore $(docs_dir)"/api/napari*.rst" \
		--ignore $(docs_dir)"/gallery/*" \
		--ignore $(docs_dir)"/jupyter_execute/*" \
		--open-browser \
		--port=0 \
		$(SPHINXOPTS)
endif

# full build, no gallery
# will not remove existing gallery files
html-noplot: clean prep-docs
ifeq ($(OS),Windows_NT)
	set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
else
	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
endif

# just napari/docs
# no generation from prep_docs scripts, no gallery
# does run notebook cells
# will not remove existing gallery files
docs: clean prep-stubs
ifeq ($(OS),Windows_NT)
	set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
else
	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
endif

# live variant of `docs`
docs-live: prep-stubs
ifeq ($(OS),Windows_NT)
	set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-autobuild -M html docs/ docs/_build -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) --ignore $(docs_dir)"/_tags/*" --ignore $(docs_dir)"/api/napari*.rst" --ignore $(docs_dir)"/gallery/*" --ignore $(docs_dir)"/jupyter_execute/*" --open-browser --port=0 -j auto $(SPHINXOPTS)
else
	NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
	sphinx-autobuild -M html docs/ docs/_build -D plot_gallery=0 \
	-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
	--ignore $(docs_dir)"/_tags/*" \
	--ignore $(docs_dir)"/api/napari*.rst" \
	--ignore $(docs_dir)"/gallery/*" \
	--ignore $(docs_dir)"/jupyter_execute/*" \
	--open-browser \
	--port=0 \
	-j auto $(SPHINXOPTS)
endif

# no notebook execution, no generation from prep_docs, no gallery
# will note remove existing gallery files
slim: clean prep-stubs
ifeq ($(OS),Windows_NT)
	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
else
	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
endif

# slim, but uses -j auto to parallelize the build
slimfast: clean prep-stubs
ifeq ($(OS),Windows_NT)
	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) -j auto $(SPHINXOPTS)
else
	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -M html docs/ docs/_build -WT --keep-going -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) -j auto $(SPHINXOPTS)
endif

# slimfast, but uses sphinx-autobuild to rebuild changed files
# this will run an initial build, because it's fast
# will not remove existing gallery files
slimfast-live: clean prep-stubs
ifeq ($(OS),Windows_NT)
	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-autobuild -M html docs/ docs/_build -D plot_gallery=0 -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) --ignore $(docs_dir)"/_tags/*" --ignore $(docs_dir)"/api/napari*.rst" --ignore $(docs_dir)"/gallery/*" --ignore $(docs_dir)"/jupyter_execute/*" --open-browser --port=0 -j auto $(SPHINXOPTS)
else
	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
	sphinx-autobuild -M html docs/ docs/_build -D plot_gallery=0 \
	-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
	--ignore $(docs_dir)"/_tags/*" \
	--ignore $(docs_dir)"/api/napari*.rst" \
	--ignore $(docs_dir)"/gallery/*" \
	--ignore $(docs_dir)"/jupyter_execute/*" \
	--open-browser \
	--port=0 \
	-j auto $(SPHINXOPTS)
endif

# slim, but with all gallery examples
# does not remove existing gallery files
slimgallery: clean clean-gallery prep-stubs
ifeq ($(OS),Windows_NT)
	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
else
	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
	sphinx-build -M html docs/ docs/_build -WT --keep-going \
	-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
	$(SPHINXOPTS)
endif

# slimgallery, but uses sphinx-autobuild to rebuild any changed examples
# no clean - call 'make clean' and/or `make clean-gallery` manually
# does not remove existing gallery files
# will rebuild whole gallery if it's not present
slimgallery-live: prep-stubs
ifeq ($(OS),Windows_NT)
	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-autobuild -M html docs/ docs/_build -T --keep-going -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) --ignore $(docs_dir)"/_tags/*" --ignore $(docs_dir)"/api/napari*.rst" --ignore $(docs_dir)"/gallery/*" --ignore $(docs_dir)"/jupyter_execute/*" --ignore $(docs_dir)/sg_execution_times.rst --watch $(docs_dir)/$(GALLERY_PATH) --open-browser --port=0 $(SPHINXOPTS)
else
	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
	sphinx-autobuild -M html docs/ docs/_build -T --keep-going \
	-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
	--ignore $(docs_dir)"/_tags/*" \
	--ignore $(docs_dir)"/api/napari*.rst" \
	--ignore $(docs_dir)"/gallery/*" \
	--ignore $(docs_dir)"/jupyter_execute/*" \
	--ignore $(docs_dir)/sg_execution_times.rst \
	--watch $(docs_dir)/$(GALLERY_PATH) \
	--open-browser \
	--port=0 \
	$(SPHINXOPTS)
endif

# slimgallery-live, but only builds a single gallery example
# pass the name of the example without .py
# e.g. slimgallery-live-vortex for vortex.py
# because it's just 1 example, uses -j auto
# Does not require a full gallery build
# Does clean existing files first, to minimize warnings
# Makefile note: this needs to be first, as the matching rule is more specific
slimgallery-live-%:
	$(MAKE) build-specific-example-live EXAMPLE_NAME=$*

# slimgallery, but only builds a single gallery example
# pass the name of the example without .py
# e.g. slimgallery-vortex for vortex.py
# because it's just 1 example, uses -j auto
# Does not require a full gallery build first
# Does clean the existing gallery to minimize warnings
slimgallery-%:
	$(MAKE) build-specific-example EXAMPLE_NAME=$*

# a target for slimgallery-%
# runs slimgallery with a single example
build-specific-example: clean clean-gallery prep-stubs
ifeq ($(OS),Windows_NT)
	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -M html docs/ docs/_build -WT --keep-going -D sphinx_gallery_conf.filename_pattern=$(EXAMPLE_NAME)".py" -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) -j auto $(SPHINXOPTS)
else
	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
	sphinx-build -M html docs/ docs/_build -WT --keep-going \
	-D sphinx_gallery_conf.filename_pattern=$(EXAMPLE_NAME)".py" \
	-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
	-j auto \
	$(SPHINXOPTS)
endif

# a target for slimgallery-live-%
# runs slimgallery-live with a single example
build-specific-example-live: clean clean-gallery prep-stubs
ifeq ($(OS),Windows_NT)
	set NB_EXECUTION_MODE=off&& set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-autobuild -M html docs/ docs/_build -T --keep-going -D sphinx_gallery_conf.filename_pattern=$(EXAMPLE_NAME)".py" -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) --ignore $(docs_dir)"/_tags/*" --ignore $(docs_dir)"/api/napari*.rst" --ignore $(docs_dir)"/gallery/*" --ignore $(docs_dir)"/jupyter_execute/*" --ignore $(docs_dir)/sg_execution_times.rst --watch $(docs_dir)/$(GALLERY_PATH)/$(EXAMPLE_NAME)".py" --open-browser --port=0 -j auto $(SPHINXOPTS)
else
	NB_EXECUTION_MODE=off NAPARI_APPLICATION_IPY_INTERACTIVE=0 \
	sphinx-autobuild -M html docs/ docs/_build -T --keep-going \
	-D sphinx_gallery_conf.filename_pattern=$(EXAMPLE_NAME)".py" \
	-D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) \
	--ignore $(docs_dir)"/_tags/*" \
	--ignore $(docs_dir)"/api/napari*.rst" \
	--ignore $(docs_dir)"/gallery/*" \
	--ignore $(docs_dir)"/jupyter_execute/*" \
	--ignore $(docs_dir)/sg_execution_times.rst \
	--watch $(docs_dir)/$(GALLERY_PATH)/$(EXAMPLE_NAME)".py" \
	--open-browser \
	--port=0 \
	-j auto \
	$(SPHINXOPTS)
endif

linkcheck-files: prep-docs
ifeq ($(OS),Windows_NT)
	set NAPARI_APPLICATION_IPY_INTERACTIVE=0&& sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build/html ${FILES} -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
else
	NAPARI_APPLICATION_IPY_INTERACTIVE=0 sphinx-build -b linkcheck -D plot_gallery=0 --color docs/ docs/_build/html ${FILES} -D sphinx_gallery_conf.examples_dirs=$(GALLERY_PATH) $(SPHINXOPTS)
endif

fallback-videos:
	for video in $(basename $(wildcard docs/_static/images/*.webm)); do \
		if [ -a $$video.mp4 ]; then \
			echo "skipping $$video.mp4"; \
			continue; \
		fi; \
		ffmpeg -i $$video.webm -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -c:v libx264 -preset slow -crf 22 -c:a aac -b:a 128k -strict -2 -y $$video.mp4; \
	done

fallback-videos-clean:
	rm -f docs/_static/images/*.mp4

spellcheck:
	pre-commit run --all-files codespell