Feature/1512 zephyr doc build

zephyr/README.rst

@@ -0,0 +1,48 @@
+.. raw:: html
+
+   <a href="https://www.mcuboot.com">
+     <p align="center">
+       <img src="doc/_static/images/logo-readme.svg">
+     </p>
+   </a>
+
+   <a href="https://bestpractices.coreinfrastructure.org/projects/74"><img
+   src="https://bestpractices.coreinfrastructure.org/projects/74/badge"></a>
+
+
+MCUboot-on-Zephyr is the MCUboot secure bootloader for 32-bit microcontrollers
+ported into the Zephyr Project ecosystem. This port "project" includes:
+
+- a reusable Zephyr-specific boot application
+- integration of the common bootloader and flash layout infrastructure
+
+.. below included in doc/introduction/mcuboot_introduction.rst
+
+
+Getting Started
+***************
+
+Welcome to MCUboot-on-Zephyr! See the `MCUboot Introduction`_ for a high-level overview,
+and the documentation's `MCUBoot Getting Started Guide`_ to start developing.
+
+.. start_include_here
+
+Community Support
+*****************
+
+Community support is provided via mailing lists and Slack; see the Resources
+below for details.
+
+.. _mcuboot-resources:
+
+Resources
+*********
+
+Here's a quick summary of resources to help you find your way around:
+
+* **MCUboot Project Website**: https://mcuboot.com
+
+.. _MCUboot Documentation: http://docs.mcuboot.com
+.. _MCUboot Introduction: http://mcuboot.com
+.. _MCUboot Getting Started Guide: http://docs.mcuboot.com
+.. _MCUboot Contribution Guide: http://docs.mcuboot.com

zephyr/VERSION

@@ -0,0 +1,5 @@
+VERSION_MAJOR = 1
+VERSION_MINOR = 9
+PATCHLEVEL = 99
+VERSION_TWEAK = 0
+EXTRAVERSION =

zephyr/doc/CMakeLists.txt

@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+project(Zephyr-Kernel-Doc LANGUAGES)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE} .. COMPONENTS doc)
+
+file(TO_CMAKE_PATH "${ZEPHYR_BASE}" ZEPHYR_BASE)
+message(STATUS "Zephyr base: ${ZEPHYR_BASE}")
+
+get_filename_component(MANIFEST_BASE ${CMAKE_CURRENT_LIST_DIR} DIRECTORY)
+
+#-------------------------------------------------------------------------------
+# Options
+
+set(SPHINXOPTS "-j auto" CACHE STRING "Default Sphinx Options")
+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(DOC_TAG "development" CACHE STRING "Documentation tag")
+set(DTS_ROOTS "${ZEPHYR_BASE}" CACHE STRING "DT bindings root folders")
+
+separate_arguments(SPHINXOPTS)
+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_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}
+)
+
+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 ${ZEPHYR_BASE}/doc/_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}
+  MANIFEST_BASE=${MANIFEST_BASE}
+  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
+
+add_doc_target(
+  html
+  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
+  MANIFEST_BASE=${MANIFEST_BASE}
+  ZEPHYR_BASE=${ZEPHYR_BASE}
+  ${SPHINXBUILD}
+    -b html
+    -c ${DOCS_CFG_DIR}
+    -d ${DOCS_DOCTREE_DIR}
+    -w ${DOCS_BUILD_DIR}/html.log
+    -t ${DOC_TAG}
+    ${SPHINXOPTS}
+    ${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)
+
+#-------------------------------------------------------------------------------
+# pdf
+
+add_doc_target(
+  latex
+  COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV}
+  MANIFEST_BASE=${MANIFEST_BASE}
+  ZEPHYR_BASE=${ZEPHYR_BASE}
+  ${SPHINXBUILD}
+    -b latex
+    -c ${DOCS_CFG_DIR}
+    -d ${DOCS_DOCTREE_DIR}
+    -w ${DOCS_BUILD_DIR}/latex.log
+    -t ${DOC_TAG}
+    -t svgconvert
+    ${SPHINXOPTS}
+    ${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}
+  MANIFEST_BASE=${MANIFEST_BASE}
+  ZEPHYR_BASE=${ZEPHYR_BASE}
+  ${SPHINXBUILD}
+    -b linkcheck
+    -c ${DOCS_CFG_DIR}
+    -d ${DOCS_DOCTREE_DIR}
+    -w ${DOCS_BUILD_DIR}/linkcheck.log
+    -t ${DOC_TAG}
+    ${SPHINXOPTS}
+    ${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
+)

zephyr/doc/Makefile

@@ -0,0 +1,33 @@
+# ------------------------------------------------------------------------------
+# Makefile for documentation build
+# SPDX-License-Identifier: Apache-2.0
+
+BUILDDIR ?= _build
+DOC_TAG ?= development
+SPHINXOPTS ?= -j auto
+LATEXMKOPTS ?= -halt-on-error -no-shell-escape
+DT_TURBO_MODE ?= 0
+
+# ------------------------------------------------------------------------------
+# Documentation targets
+
+.PHONY: configure clean html html-fast latex pdf doxygen
+
+html-fast:
+	${MAKE} html DT_TURBO_MODE=1
+
+html latex pdf linkcheck doxygen: configure
+	cmake --build ${BUILDDIR} --target $@
+
+configure:
+	cmake \
+		-GNinja \
+		-B${BUILDDIR} \
+		-S. \
+		-DDOC_TAG=${DOC_TAG} \
+		-DSPHINXOPTS="${SPHINXOPTS}" \
+		-DLATEXMKOPTS="${LATEXMKOPTS}" \
+		-DDT_TURBO_MODE=${DT_TURBO_MODE}
+
+clean:
+	cmake --build ${BUILDDIR} --target clean