114 lines
3.3 KiB
Makefile
114 lines
3.3 KiB
Makefile
# Makefile for Sphinx documentation
|
||
#
|
||
|
||
# You can set these variables from the command line.
|
||
PYTHON = python3
|
||
VENVDIR = ./.venv
|
||
SPHINXBUILD = $(VENVDIR)/bin/sphinx-build
|
||
#SPHINXOPTS = --fail-on-warning --keep-going
|
||
SPHINXOPTS =
|
||
SOURCEDIR = docs
|
||
BUILDDIR = docs/_build
|
||
BUILDER = html
|
||
JOBS = auto
|
||
SPHINXLINT = $(VENVDIR)/bin/sphinx-lint
|
||
REQUIREMENTS = requirements.txt
|
||
|
||
# Internal variables.
|
||
_ALL_SPHINX_OPTS = --jobs $(JOBS) $(SPHINXOPTS)
|
||
|
||
.PHONY: help
|
||
help:
|
||
@echo "Please use \`make <target>' where <target> is one of"
|
||
@echo " venv to create a venv with necessary tools"
|
||
@echo " html to make standalone HTML files"
|
||
@echo " linkcheck to check all external links for integrity"
|
||
@echo " htmlview to open the index page built by the html target in your browser"
|
||
@echo " htmllive to rebuild and reload HTML files in your browser"
|
||
@echo " clean to remove the venv and build files"
|
||
@echo " check to run a check for frequent markup errors"
|
||
@echo " lint to lint all the files"
|
||
|
||
.PHONY: clean
|
||
clean: clean-venv
|
||
-rm -rf $(BUILDDIR)/*
|
||
|
||
.PHONY: clean-venv
|
||
clean-venv:
|
||
rm -rf $(VENVDIR)
|
||
|
||
.PHONY: venv
|
||
venv:
|
||
@if [ -d $(VENVDIR) ] ; then \
|
||
echo "venv already exists."; \
|
||
echo "To recreate it, remove it first with \`make clean-venv'."; \
|
||
else \
|
||
$(MAKE) ensure-venv; \
|
||
fi
|
||
|
||
.PHONY: ensure-venv
|
||
ensure-venv:
|
||
@if [ ! -d $(VENVDIR) ] ; then \
|
||
echo "Creating venv in $(VENVDIR)"; \
|
||
if $(UV) --version >/dev/null 2>&1; then \
|
||
$(UV) venv $(VENVDIR); \
|
||
VIRTUAL_ENV=$(VENVDIR) $(UV) pip install -r $(REQUIREMENTS); \
|
||
else \
|
||
$(PYTHON) -m venv $(VENVDIR); \
|
||
$(VENVDIR)/bin/python3 -m pip install --upgrade pip; \
|
||
$(VENVDIR)/bin/python3 -m pip install -r $(REQUIREMENTS); \
|
||
fi; \
|
||
echo "The venv has been created in the $(VENVDIR) directory"; \
|
||
fi
|
||
|
||
.PHONY: htmlview
|
||
htmlview: html
|
||
$(PYTHON) -c "import os, webbrowser; webbrowser.open('file://' + os.path.realpath('docs/_build/html/index.html'))"
|
||
|
||
# .PHONY: htmllive
|
||
# htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
|
||
# # Arbitrarily selected ephemeral port between 49152–65535
|
||
# # to avoid conflicts with other processes:
|
||
# htmllive: SPHINXOPTS = --re-ignore="/\.idea/|/venv/" --open-browser --delay 0 --port 0
|
||
# htmllive: html
|
||
|
||
.PHONY: htmllive
|
||
htmllive: SPHINXBUILD = $(VENVDIR)/bin/sphinx-autobuild
|
||
htmllive: SPHINXOPTS = --ignore "*.swp" --open-browser --port 8000 #0
|
||
htmllive:
|
||
$(SPHINXBUILD) $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"
|
||
|
||
|
||
.PHONY: check
|
||
check: ensure-venv
|
||
# Ignore the tools and venv dirs and check that the default role is not used.
|
||
$(SPHINXLINT) -i tools -i $(VENVDIR) --enable default-role
|
||
|
||
.PHONY: _ensure-package
|
||
_ensure-package: venv
|
||
if $(UV) --version >/dev/null 2>&1; then \
|
||
VIRTUAL_ENV=$(VENVDIR) $(UV) pip install $(PACKAGE); \
|
||
else \
|
||
$(VENVDIR)/bin/python3 -m pip install $(PACKAGE); \
|
||
fi
|
||
|
||
.PHONY: _ensure-pre-commit
|
||
_ensure-pre-commit:
|
||
make _ensure-package PACKAGE=pre-commit
|
||
|
||
.PHONY: lint
|
||
lint: _ensure-pre-commit
|
||
$(VENVDIR)/bin/python3 -m pre_commit run --all-files
|
||
|
||
# Defined so that "include/release-cycle.json"
|
||
# doesn't fall through to the catch-all target.
|
||
include/release-cycle.json:
|
||
@exit
|
||
|
||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||
# "make mode" option.
|
||
.PHONY: Makefile
|
||
%: Makefile ensure-venv
|
||
$(SPHINXBUILD) -M $@ "${SOURCEDIR}" "$(BUILDDIR)" $(_ALL_SPHINX_OPTS)
|
||
|