From fc942ef7d30dea3a5b4e0d9644cc9f586385ecf0 Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Wed, 12 Jan 2022 13:41:15 +0100 Subject: [PATCH] doc: use new kconfig extension Enable the new extension and delete usage of the old script/extensions. Signed-off-by: Gerard Marull-Paretas --- doc/CMakeLists.txt | 67 ++-------------------------- doc/Makefile | 4 +- doc/application/index.rst | 4 +- doc/conf.py | 9 +++- doc/guides/build/kconfig/setting.rst | 8 ++-- doc/guides/docs/index.rst | 10 ++--- doc/kconfig.rst | 8 ++++ 7 files changed, 29 insertions(+), 81 deletions(-) create mode 100644 doc/kconfig.rst diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index ed03b4bb49..5528281b0f 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -64,7 +64,7 @@ set(DOCS_LATEX_DIR ${CMAKE_CURRENT_BINARY_DIR}/latex) # # 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 or Kconfig generators. +# devicetree generator. # function(add_doc_target name) add_custom_target(${name} ${ARGN}) @@ -94,67 +94,6 @@ set_target_properties( ADDITIONAL_CLEAN_FILES "${DOXY_OUT}" ) -#------------------------------------------------------------------------------- -# kconfig - -set(KCONFIG_BINARY_DIR ${CMAKE_BINARY_DIR}/Kconfig) - -foreach(module_name ${ZEPHYR_MODULE_NAMES}) - zephyr_string(SANITIZE TOUPPER MODULE_NAME_UPPER ${module_name}) - list(APPEND - ZEPHYR_KCONFIG_MODULES - "ZEPHYR_${MODULE_NAME_UPPER}_MODULE_DIR=${ZEPHYR_${MODULE_NAME_UPPER}_MODULE_DIR}" - ) - - if(ZEPHYR_${MODULE_NAME_UPPER}_KCONFIG) - list(APPEND - ZEPHYR_KCONFIG_MODULES - "ZEPHYR_${MODULE_NAME_UPPER}_KCONFIG=${ZEPHYR_${MODULE_NAME_UPPER}_KCONFIG}" - ) - endif() -endforeach() - -if(WIN32) - set(SEP $) -else() - set(SEP :) -endif() - -set(GEN_KCONFIG_REST_SCRIPT ${CMAKE_CURRENT_LIST_DIR}/_scripts/gen_kconfig_rest.py) - -add_custom_target( - kconfig - COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCS_SRC_DIR}/reference/kconfig - COMMAND ${CMAKE_COMMAND} -E env - PYTHONPATH=${ZEPHYR_BASE}/scripts/kconfig${SEP}$ENV{PYTHONPATH} - ZEPHYR_BASE=${ZEPHYR_BASE} - srctree=${ZEPHYR_BASE} - BOARD_DIR=boards/*/* - ARCH=* - ARCH_DIR=arch - SOC_DIR=soc - TOOLCHAIN_HAS_NEWLIB=y - KCONFIG_BINARY_DIR=${KCONFIG_BINARY_DIR} - KCONFIG_WARN_UNDEF=y - KCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE} - KCONFIG_DOC_MODE=1 - ${ZEPHYR_KCONFIG_MODULES} - ${PYTHON_EXECUTABLE} ${GEN_KCONFIG_REST_SCRIPT} ${DOCS_SRC_DIR}/reference/kconfig/ - --separate-all-index - --keep-module-paths - --modules Architecture,arch,${ZEPHYR_BASE}/arch - Driver,drivers,${ZEPHYR_BASE}/drivers - Kernel,kernel,${ZEPHYR_BASE}/kernel - Library,lib,${ZEPHYR_BASE}/lib - Subsystem,subsys,${ZEPHYR_BASE}/subsys - "External Module,modules,${ZEPHYR_BASE}/modules" - - VERBATIM - COMMENT "Generating Kconfig documentation..." -) - -set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_KCONFIG_REST_SCRIPT}) - #------------------------------------------------------------------------------- # devicetree @@ -210,7 +149,7 @@ set_target_properties( ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_HTML_DIR};${DOCS_DOCTREE_DIR}" ) -add_dependencies(html devicetree kconfig) +add_dependencies(html devicetree) #------------------------------------------------------------------------------- # pdf @@ -238,7 +177,7 @@ set_target_properties( ADDITIONAL_CLEAN_FILES "${DOCS_SRC_DIR};${DOCS_LATEX_DIR};${DOCS_DOCTREE_DIR}" ) -add_dependencies(latex kconfig devicetree) +add_dependencies(latex devicetree) if(LATEX_PDFLATEX_FOUND AND LATEXMK) if(WIN32) diff --git a/doc/Makefile b/doc/Makefile index f311b634fc..3dc00c0db5 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -6,7 +6,6 @@ BUILDDIR ?= _build DOC_TAG ?= development SPHINXOPTS ?= -j auto LATEXMKOPTS ?= -halt-on-error -no-shell-escape -KCONFIG_TURBO_MODE ?= 0 DT_TURBO_MODE ?= 0 # ------------------------------------------------------------------------------ @@ -15,7 +14,7 @@ DT_TURBO_MODE ?= 0 .PHONY: configure clean html html-fast latex pdf doxygen html-fast: - ${MAKE} html KCONFIG_TURBO_MODE=1 DT_TURBO_MODE=1 + ${MAKE} html DT_TURBO_MODE=1 html latex pdf doxygen: configure cmake --build ${BUILDDIR} --target $@ @@ -28,7 +27,6 @@ configure: -DDOC_TAG=${DOC_TAG} \ -DSPHINXOPTS="${SPHINXOPTS}" \ -DLATEXMKOPTS="${LATEXMKOPTS}" \ - -DKCONFIG_TURBO_MODE=${KCONFIG_TURBO_MODE} \ -DDT_TURBO_MODE=${DT_TURBO_MODE} clean: diff --git a/doc/application/index.rst b/doc/application/index.rst index c44a8bc8eb..8db15d05c6 100644 --- a/doc/application/index.rst +++ b/doc/application/index.rst @@ -511,8 +511,8 @@ started. See :ref:`setting_configuration_values` for detailed documentation on setting Kconfig configuration values. The :ref:`initial-conf` section on the same page -explains how the initial configuration is derived. See -:ref:`configuration_options` for a complete list of configuration options. +explains how the initial configuration is derived. See :ref:`kconfig-search` +for a complete list of configuration options. See :ref:`hardening` for security information related with Kconfig options. The other pages in the :ref:`Kconfig section of the manual ` are also diff --git a/doc/conf.py b/doc/conf.py index 114d9b27fa..e9d7787576 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -74,7 +74,7 @@ extensions = [ "sphinx.ext.graphviz", "zephyr.application", "zephyr.html_redirects", - "zephyr.kconfig-role", + "zephyr.kconfig", "zephyr.dtcompatible-role", "zephyr.link-roles", "sphinx_tabs.tabs", @@ -150,7 +150,7 @@ html_context = { "display_vcs_link": True, "reference_links": { "API": f"{reference_prefix}/doxygen/html/index.html", - "Kconfig Options": f"{reference_prefix}/reference/kconfig/index.html", + "Kconfig Options": f"{reference_prefix}/kconfig.html", "Devicetree Bindings": f"{reference_prefix}/reference/devicetree/bindings.html", } } @@ -241,6 +241,11 @@ vcs_link_exclude = [ "reference/devicetree/compatibles.*", ] +# -- Options for zephyr.kconfig ------------------------------------------- + +kconfig_generate_db = True +kconfig_ext_paths = [ZEPHYR_BASE] + # -- Options for zephyr.external_content ---------------------------------- external_content_contents = [ diff --git a/doc/guides/build/kconfig/setting.rst b/doc/guides/build/kconfig/setting.rst index fa919f6256..bad7d094d6 100644 --- a/doc/guides/build/kconfig/setting.rst +++ b/doc/guides/build/kconfig/setting.rst @@ -7,8 +7,8 @@ The :ref:`menuconfig and guiconfig interfaces ` can be used to test out configurations during application development. This page explains how to make settings permanent. -An auto-generated list of all Kconfig options can be found in the :ref:`Kconfig -symbol reference `. +All Kconfig options can be searched in the :ref:`Kconfig search page +`. .. note:: @@ -115,8 +115,8 @@ Assignments in configuration files are only respected if the dependencies for the symbol are satisfied. A warning is printed otherwise. To figure out what the dependencies of a symbol are, use one of the :ref:`interactive configuration interfaces ` (you can jump directly to a symbol with -:kbd:`/`), or look up the symbol in the :ref:`Kconfig symbol reference -`. +:kbd:`/`), or look up the symbol in the :ref:`Kconfig search page +`. .. _initial-conf: diff --git a/doc/guides/docs/index.rst b/doc/guides/docs/index.rst index 6d31053cd2..fbb19a4149 100644 --- a/doc/guides/docs/index.rst +++ b/doc/guides/docs/index.rst @@ -245,15 +245,13 @@ declarations. This warning may be caused by different Sphinx/Breathe issues: Developer-mode Document Building ******************************** -Building the documentation for all the Kconfig options significantly -adds to the total doc build time. When making and testing major changes -to the documentation, we provide an option to temporarily stub-out -the auto-generated configuration and Devicetree bindings documentation so the -doc build process runs much faster. +When making and testing major changes to the documentation, we provide an option +to temporarily stub-out the auto-generated Devicetree bindings documentation so +the doc build process runs faster. To enable this mode, set the following option when invoking cmake:: - -DKCONFIG_TURBO_MODE=1 -DDT_TURBO_MODE=1 + -DDT_TURBO_MODE=1 or invoke make with the following target:: diff --git a/doc/kconfig.rst b/doc/kconfig.rst new file mode 100644 index 0000000000..1123de2adb --- /dev/null +++ b/doc/kconfig.rst @@ -0,0 +1,8 @@ +:orphan: + +.. _kconfig-search: + +Kconfig Search +============== + +.. kconfig:search::