0001. zdocs is a Zephyr module, included by name

Status

Accepted.

Context

Zephyr already has a mechanism for shipping reusable CMake to a consuming project — the module system — and every intended consumer of this engine is already a Zephyr workspace. The question was therefore not whether to be a Zephyr module but how a consumer reaches the engine’s CMake surface once it is one.

The obvious route does not work. find_package(Zephyr COMPONENTS doc) is a reduced flow: it does not reliably run a module’s own CMakeLists.txt, so a module cannot count on being able to define its functions that way.

Decision

zdocs is a Zephyr module whose CMake is consumed by name, not by path:

list(APPEND CMAKE_MODULE_PATH ${ZEPHYR_ZDOCS_MODULE_DIR}/cmake)
include(zdocs)

Zephyr’s module system sets ZEPHYR_ZDOCS_MODULE_DIR when it loads the module, whether the module is a project of the active west manifest or is supplied out-of-tree with EXTRA_ZEPHYR_MODULES. The consumer therefore never writes a path into the engine.

Everything the engine needs from the consuming project arrives through the ZDOCS_* variables (see The ZDOCS_* contract), set before include(zdocs). The engine ships no project-specific default and guesses nothing: a missing ZDOCS_PROJECT_BASE is a fatal error at configure time, not a silently-wrong path at build time.