doc/Makefile

# ------------------------------------------------------------------------------
# Makefile for documentation build
# SPDX-License-Identifier: Apache-2.0

BUILDDIR ?= _build
DOC_TAG ?= development
SPHINXOPTS ?= -j auto -W --keep-going -T
SPHINXOPTS_EXTRA ?=
LATEXMKOPTS ?= -halt-on-error -no-shell-escape
DT_TURBO_MODE ?= 0
HW_FEATURES_TURBO_MODE ?= 0
HW_FEATURES_VENDOR_FILTER ?=
NO_EXTERNAL_DEPS ?= 0
DOXYGEN_FORCE_SINGLE_THREAD ?= 0
SKIP_DOXYGEN ?= 0
SKIP_KCONFIG ?= 0
SKIP_EXTERNAL_CONTENT ?= 0

# Each SKIP_* switch drops one expensive autogenerated layer (Doxygen, Kconfig
# reference, or the board/sample/snippet pages copied in from the main tree);
# it can be set on its own (e.g. `make html SKIP_DOXYGEN=1`) and is turned
# into a Sphinx tag read by conf.py. Content from a skipped layer degrades to
# a placeholder / plain text, so any such build is a preview and must not be
# published.
SKIP_TAGS = \
	$(if $(filter-out 0,$(SKIP_DOXYGEN)),-t skip_doxygen) \
	$(if $(filter-out 0,$(SKIP_KCONFIG)),-t skip_kconfig) \
	$(if $(filter-out 0,$(SKIP_EXTERNAL_CONTENT)),-t skip_external_content)

# ------------------------------------------------------------------------------
# Documentation targets

.PHONY: configure clean html html-fast html-minimal html-live html-live-fast latex pdf doxygen doxygen-xml doxygen-coverage doxygen-coverage-json

html-fast:
	${MAKE} html DT_TURBO_MODE=1 HW_FEATURES_TURBO_MODE=1

# Minimal preview build: html-fast with every SKIP_* switch enabled. The
# fastest way to preview narrative .rst changes; not suitable for publishing
# (see SKIP_TAGS).
html-minimal:
	${MAKE} html-fast \
		SKIP_DOXYGEN=1 SKIP_KCONFIG=1 SKIP_EXTERNAL_CONTENT=1

html-live-fast:
	${MAKE} html-live DT_TURBO_MODE=1 HW_FEATURES_TURBO_MODE=1

doxygen-coverage doxygen-coverage-json:
	${MAKE} configure DOXYGEN_FORCE_SINGLE_THREAD=1
	cmake --build ${BUILDDIR} --target $@

html html-live latex pdf linkcheck doxygen doxygen-xml: configure
	cmake --build ${BUILDDIR} --target $@

configure:
	cmake \
		-GNinja \
		-B${BUILDDIR} \
		-S. \
		-DDOC_TAG=${DOC_TAG} \
		-DSPHINXOPTS="${SPHINXOPTS}" \
		-DSPHINXOPTS_EXTRA="${SPHINXOPTS_EXTRA} ${SKIP_TAGS}" \
		-DLATEXMKOPTS="${LATEXMKOPTS}" \
		-DDT_TURBO_MODE=${DT_TURBO_MODE} \
		-DHW_FEATURES_TURBO_MODE=${HW_FEATURES_TURBO_MODE} \
		-DHW_FEATURES_VENDOR_FILTER=${HW_FEATURES_VENDOR_FILTER} \
		-DNO_EXTERNAL_DEPS=${NO_EXTERNAL_DEPS} \
		-DDOXYGEN_FORCE_SINGLE_THREAD=${DOXYGEN_FORCE_SINGLE_THREAD}

clean:
	cmake --build ${BUILDDIR} --target clean