bartoszek/zephyr
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
94de015498
zephyr/doc/CMakeLists.txt
Benjamin Cabé 444964e031 doc: extensions: boards: Add hardware features filter to board catalog 
Add a new hardware features filter to the board catalog that allows
users to filter boards based on their supported hardware capabilities.
The features are extracted from the devicetree files and organized by
binding type.

Key changes:
- Extract hardware feature descriptions from devicetree bindings
- Add HW_FEATURES_TURBO_MODE option to skip feature generation for
  faster builds (similar to DT_TURBO_MODE)
- Add tag-based UI for filtering boards by hardware features

The feature can be disabled for faster documentation builds using
-DHW_FEATURES_TURBO_MODE=1 or by using 'make html-fast'.

Signed-off-by: Benjamin Cabé <benjamin@zephyrproject.org>
2025-02-20 15:08:50 +00:00

304 lines
8.1 KiB
CMake
Raw Blame History

# SPDX-License-Identifier: Apache-2.0
cmake_minimum_required(VERSION 3.20.0)
project(Zephyr-Kernel-Doc LANGUAGES)
set(MIN_WEST_VERSION 1.0.0)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE} .. COMPONENTS doc)
file(TO_CMAKE_PATH "${ZEPHYR_BASE}" ZEPHYR_BASE)
message(STATUS "Zephyr base: ${ZEPHYR_BASE}")
#-------------------------------------------------------------------------------
# Options
set(SPHINXOPTS "-j auto -W --keep-going -T" CACHE STRING "Default Sphinx Options")
set(SPHINXOPTS_EXTRA "" CACHE STRING "Extra Sphinx Options (added to defaults)")
set(LATEXMKOPTS "-halt-on-error -no-shell-escape" CACHE STRING "Default latexmk options")
set(DT_TURBO_MODE OFF CACHE BOOL "Enable DT turbo mode")
set(HW_FEATURES_TURBO_MODE OFF CACHE BOOL "Enable HW features turbo mode")
set(DOC_TAG "development" CACHE STRING "Documentation tag")
set(DTS_ROOTS "${ZEPHYR_BASE}" CACHE STRING "DT bindings root folders")
separate_arguments(SPHINXOPTS)
separate_arguments(SPHINXOPTS_EXTRA)
separate_arguments(LATEXMKOPTS)
#-------------------------------------------------------------------------------
# Dependencies
find_package(Doxygen REQUIRED dot)
find_program(SPHINXBUILD sphinx-build)
if(NOT SPHINXBUILD)
message(FATAL_ERROR "The 'sphinx-build' command was not found")
endif()
find_program(SPHINXAUTOBUILD sphinx-autobuild)
find_package(LATEX COMPONENTS PDFLATEX)
find_program(LATEXMK latexmk)
if(NOT LATEX_PDFLATEX_FOUND OR NOT LATEXMK)
message(WARNING "LaTeX components not found. PDF build will not be available.")
endif()
#-------------------------------------------------------------------------------
# Environment & Paths
set(SPHINX_ENV
DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}
DOT_EXECUTABLE=${DOXYGEN_DOT_EXECUTABLE}
DOCS_HTML_DIR=${CMAKE_CURRENT_BINARY_DIR}/html
)
if(DEFINED ENV{ZEPHYR_DOXYGEN_OVERLAY})
if(EXISTS $ENV{ZEPHYR_DOXYGEN_OVERLAY})
set(INCLUDE_CUSTOM_FILE "@INCLUDE = $ENV{ZEPHYR_DOXYGEN_OVERLAY}")
else()
message(FATAL_ERROR "Zephyr Doxygen overlay $ENV{ZEPHYR_DOXYGEN_OVERLAY} does not exist!")
endif()
else()
set(INCLUDE_CUSTOM_FILE "")
endif()
set(DOCS_CFG_DIR ${CMAKE_CURRENT_LIST_DIR})
set(DOCS_DOCTREE_DIR ${CMAKE_CURRENT_BINARY_DIR}/doctrees)
set(DOCS_BUILD_DIR ${CMAKE_CURRENT_BINARY_DIR})
set(DOCS_SRC_DIR ${CMAKE_CURRENT_BINARY_DIR}/src)
set(DOCS_HTML_DIR ${CMAKE_CURRENT_BINARY_DIR}/html)
set(DOCS_LINKCHECK_DIR ${CMAKE_CURRENT_BINARY_DIR}/linkcheck)
set(DOCS_LATEX_DIR ${CMAKE_CURRENT_BINARY_DIR}/latex)
if(WIN32)
set(SEP $<SEMICOLON>)
else()
set(SEP :)
endif()
#-------------------------------------------------------------------------------
# Functions
# Create a custom doc target.
#
# This function has the same signature as `add_custom_target()`
#
# The function will create two targets for the doc build system.
# - Target 1 named: `<name>`
# - Target 2 named: `<name>-nodeps`
#
# Both targets will produce same result, but target 2 must have no dependencies.
# This is useful to, e.g. re-run the Sphinx build without dependencies such as
# devicetree generator.
#
function(add_doc_target name)
add_custom_target(${name} ${ARGN})
add_custom_target(${name}-nodeps ${ARGN})
endfunction()
#-------------------------------------------------------------------------------
# Doxygen (standalone)
set(DOXY_OUT ${CMAKE_CURRENT_BINARY_DIR}/doxygen)
set(DOXYFILE_IN ${CMAKE_CURRENT_LIST_DIR}/zephyr.doxyfile.in)
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/zephyr.doxyfile)
set(ZEPHYR_VERSION "${Zephyr_VERSION}")
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
add_custom_target(
doxygen
COMMAND
${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
COMMENT "Running Doxygen..."
)
set_target_properties(
doxygen
PROPERTIES
ADDITIONAL_CLEAN_FILES "${DOXY_OUT}"
)
#-------------------------------------------------------------------------------
# devicetree
set(GEN_DEVICETREE_REST_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/_scripts/gen_devicetree_rest.py)
set(DTS_ARGS)
foreach(root ${DTS_ROOTS})
list(APPEND DTS_ARGS --dts-root ${root})
endforeach()
if(DT_TURBO_MODE)
list(APPEND DTS_ARGS --turbo-mode)
endif()
add_custom_target(
devicetree
COMMAND ${CMAKE_COMMAND} -E env
PYTHONPATH=${ZEPHYR_BASE}/scripts/dts/python-devicetree/src${SEP}$ENV{PYTHONPATH}
ZEPHYR_BASE=${ZEPHYR_BASE}
${PYTHON_EXECUTABLE} ${GEN_DEVICETREE_REST_SCRIPT}
--vendor-prefixes ${ZEPHYR_BASE}/dts/bindings/vendor-prefixes.txt
${DTS_ARGS}
${DOCS_SRC_DIR}/build/dts/api
VERBATIM
USES_TERMINAL
COMMENT "Generating Devicetree bindings documentation..."
)
set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_DEVICETREE_REST_SCRIPT})
#-------------------------------------------------------------------------------
# html
set(SPHINX_TAGS "${DOC_TAG}")
if(HW_FEATURES_TURBO_MODE)
list(APPEND SPHINX_TAGS "hw_features_turbo")
endif()
set(SPHINX_TAGS_ARGS "")
foreach(tag ${SPHINX_TAGS})
list(APPEND SPHINX_TAGS_ARGS "-t" "${tag}")
endforeach()
add_doc_target(
html
COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_HTML_DIR}
${SPHINXBUILD}
-b html
-c ${DOCS_CFG_DIR}
-d ${DOCS_DOCTREE_DIR}
-w ${DOCS_BUILD_DIR}/html.log
${SPHINX_TAGS_ARGS}
${SPHINXOPTS}
${SPHINXOPTS_EXTRA}
${DOCS_SRC_DIR}
${DOCS_HTML_DIR}
USES_TERMINAL
COMMENT "Running Sphinx HTML build..."
)
set_target_properties(
html html-nodeps
PROPERTIES
ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_HTML_DIR};${DOCS_DOCTREE_DIR}"
)
add_dependencies(html devicetree)
#-------------------------------------------------------------------------------
# html-live
add_doc_target(
html-live
COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
${SPHINXAUTOBUILD}
--watch ${DOCS_CFG_DIR}
--ignore ${DOCS_BUILD_DIR}
-b html
-c ${DOCS_CFG_DIR}
-d ${DOCS_DOCTREE_DIR}
-w ${DOCS_BUILD_DIR}/html.log
${SPHINX_TAGS_ARGS}
${SPHINXOPTS}
${SPHINXOPTS_EXTRA}
${DOCS_SRC_DIR}
${DOCS_HTML_DIR}
USES_TERMINAL
COMMENT "Running Sphinx HTML autobuild..."
)
set_target_properties(
html-live html-live-nodeps
PROPERTIES
ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_HTML_DIR};${DOCS_DOCTREE_DIR}"
)
add_dependencies(html-live devicetree)
#-------------------------------------------------------------------------------
# pdf
add_doc_target(
latex
COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_LATEX_DIR}
${SPHINXBUILD}
-b latex
-c ${DOCS_CFG_DIR}
-d ${DOCS_DOCTREE_DIR}
-w ${DOCS_BUILD_DIR}/latex.log
${SPHINX_TAGS_ARGS}
-t convertimages
${SPHINXOPTS}
${SPHINXOPTS_EXTRA}
${DOCS_SRC_DIR}
${DOCS_LATEX_DIR}
USES_TERMINAL
COMMENT "Running Sphinx LaTeX build..."
)
set_target_properties(
latex latex-nodeps
PROPERTIES
ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LATEX_DIR};${DOCS_DOCTREE_DIR}"
)
add_dependencies(latex devicetree)
if(LATEX_PDFLATEX_FOUND AND LATEXMK)
if(WIN32)
set(PDF_BUILD_COMMAND "make.bat")
else()
find_program(MAKE make)
if(NOT MAKE)
message(FATAL_ERROR "The 'make' command was not found")
endif()
set(PDF_BUILD_COMMAND ${MAKE})
endif()
add_custom_target(
pdf
COMMAND ${CMAKE_COMMAND} -E env LATEXMKOPTS="${LATEXMKOPTS}"
${PDF_BUILD_COMMAND}
WORKING_DIRECTORY ${DOCS_LATEX_DIR}
COMMENT "Building PDF file..."
USES_TERMINAL
)
add_dependencies(pdf latex)
endif()
#-------------------------------------------------------------------------------
# linkcheck
add_doc_target(
linkcheck
COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} OUTPUT_DIR=${DOCS_LINKCHECK_DIR}
${SPHINXBUILD}
-b linkcheck
-c ${DOCS_CFG_DIR}
-d ${DOCS_DOCTREE_DIR}
-w ${DOCS_BUILD_DIR}/linkcheck.log
${SPHINX_TAGS_ARGS}
${SPHINXOPTS}
${SPHINXOPTS_EXTRA}
${DOCS_SRC_DIR}
${DOCS_LINKCHECK_DIR}
USES_TERMINAL
COMMENT "Running Sphinx link check..."
)
set_target_properties(
linkcheck linkcheck-nodeps
PROPERTIES
ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LINKCHECK_DIR};${DOCS_DOCTREE_DIR}"
)
add_dependencies(linkcheck devicetree)
#-------------------------------------------------------------------------------
# others
add_custom_target(
pristine
COMMAND ${CMAKE_COMMAND} -P ${ZEPHYR_BASE}/cmake/pristine.cmake
)
Reference in New Issue View Git Blame Copy Permalink