diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000000..76b48e3c50 --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,309 @@ +# Copyright (c) 2025 Nordic Semiconductor ASA +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + +# Builds combined documentation for all documentation sets: nRF (including +# Doxygen documentation), S115, etc. +# +# We use our own Sphinx configuration files when building the documentation set +# for each repository, instead of reusing configuration files. See e.g. +# doc/nrfbm/conf.py. + +cmake_minimum_required(VERSION 3.20.0) +project(nrf-sdk-bm-doc LANGUAGES NONE) + +find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE} COMPONENTS doc) + +#------------------------------------------------------------------------------- +# Options + +set(SPHINXOPTS "-j auto -W --keep-going -T" CACHE STRING "Default Sphinx Options") +set(SPHINXOPTS_EXTRA "" CACHE STRING "Extra Sphinx Options") + +separate_arguments(SPHINXOPTS) +separate_arguments(SPHINXOPTS_EXTRA) + +#------------------------------------------------------------------------------- +# Dependencies + +find_package(Python 3.10) +set(DOXYGEN_SKIP_DOT True) +find_package(Doxygen 1.12.0 REQUIRED) + +find_program(SPHINXBUILD sphinx-build) +if(NOT SPHINXBUILD) + message(FATAL_ERROR "The 'sphinx-build' command was not found") +endif() + +find_program(SPHINXAUTOBUILD sphinx-autobuild) +if(NOT SPHINXAUTOBUILD) + message(WARNING "sphinx-autobuild not found, HTML hot reloading will not be available.") +endif() + +set(KCONFIG_BINARY_DIR ${CMAKE_BINARY_DIR}/kconfig) +list(INSERT MODULE_EXT_ROOT 0 ${ZEPHYR_BASE}) +file(MAKE_DIRECTORY ${KCONFIG_BINARY_DIR}) + +#------------------------------------------------------------------------------- +# Functions + +# Add a new Doxygen docset. +# +# Args: +# - name: Docset name. +# - sources: Sources. +# - version: Docset version. +# - STANDALONE: Use if docset is Doxygen-only, i.e., without Sphinx. +# +# Configured targets (if STANDALONE): +# - ${name}: Run Doxygen build. +# - ${name}-clean: Clean build artifacts. +# +# Configured targets (if NOT STANDALONE): +# - ${name}-doxygen: Run Doxygen build. +# - ${name}-doxygen-clean: Clean build artifacts. +# +function(add_doxygen_docset name sources version) + cmake_parse_arguments(DOXYGEN "STANDALONE" "" "" ${ARGN}) + set(DOCSET_BUILD_DIR ${CMAKE_BINARY_DIR}/html/${name}) + set(DOCSET_SOURCE_BASE ${sources}) + set(DOCSET_VERSION ${version}) + + if(NOT DOXYGEN_STANDALONE) + set(SUFFIX "-doxygen") + set(DOCSET_BUILD_DIR ${DOCSET_BUILD_DIR}/doxygen) + endif() + + configure_file(${CMAKE_CURRENT_LIST_DIR}/${name}/${name}.doxyfile.in ${CMAKE_BINARY_DIR}/${name}.doxyfile) + + add_custom_target( + ${name}${SUFFIX} + COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_BUILD_DIR} + COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/${name}.doxyfile + USES_TERMINAL + COMMENT "Building ${name} Doxygen docset..." + ) + + add_custom_target( + ${name}${SUFFIX}-clean + COMMAND ${CMAKE_COMMAND} -E rm -rf ${DOCSET_BUILD_DIR} + ) +endfunction() + +# Add a new docset. +# +# Args: +# - name: Docset name. +# - version: Docset version. +# - DODGY: Enable/disable "dodgy" mode. If enabled "-W" (warnings as errors) +# option will be disabled. It can be useful for external docsets that are +# likely to generate build warnings. +# - SPHINXOPTS: Docset specific Sphinx options +# +# This function configures multiple targets which can be used to build a docset. +# The docset configuration (conf.py) is expected to be at the ${name} folder +# (relative to the current directory). The sources are taken from the +# ${name}/src folder (relative to the build directory). This means that docsets +# need to make use of the external_content extension in order to gather all +# docset sources into that folder. +# +# Configured targets: +# - ${name}: Run Sphinx "html" build. +# - ${name}-live: Run Sphinx "html" live build (if sphinx-autobuild is +# available). +# - ${name}-linkcheck: Run Sphinx "linkcheck" target. +# - ${name}-clean: Clean build artifacts. +# +function(add_docset name version) + cmake_parse_arguments(DOCSET "DODGY" "" "SPHINXOPTS" ${ARGN}) + + set(DOCSET_CFG_DIR ${CMAKE_CURRENT_LIST_DIR}/${name}) + set(DOCSET_BUILD_DIR ${CMAKE_BINARY_DIR}/${name}) + set(DOCSET_SRC_DIR ${CMAKE_BINARY_DIR}/${name}/src) + set(DOCSET_DOCTREE_DIR ${CMAKE_BINARY_DIR}/${name}/doctree) + set(DOCSET_HTML_DIR ${CMAKE_BINARY_DIR}/html/${name}) + set(DOCSET_LINKCHECK_DIR ${CMAKE_BINARY_DIR}/linkcheck/${name}) + set(DOCSET_MAKE_DIRS ${DOCSET_BUILD_DIR};${DOCSET_SRC_DIR};${DOCSET_HTML_DIR}) + set(DOCSET_CLEAN_DIRS ${DOCSET_BUILD_DIR};${DOCSET_HTML_DIR}) + set(DOCSET_ENV DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE};DOCSET_VERSION=${version};DOCS_HTML_DIR=${DOCSET_HTML_DIR}) + + if(${DOCSET_DODGY}) + list(REMOVE_ITEM SPHINXOPTS "-W" "--keep-going") + endif() + + add_doc_target( + ${name} + COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_MAKE_DIRS} + COMMAND ${CMAKE_COMMAND} -E env ${DOCSET_ENV} + ${SPHINXBUILD} + -b html + -c ${DOCSET_CFG_DIR} + -d ${DOCSET_DOCTREE_DIR} + -w ${DOCSET_BUILD_DIR}/html.log + ${SPHINXOPTS} + ${SPHINXOPTS_EXTRA} + ${DOCSET_SPHINXOPTS} + ${EXTRA_ARGS} + ${DOCSET_SRC_DIR} + ${DOCSET_HTML_DIR} + USES_TERMINAL + COMMENT "Building ${name} docset..." + ) + + if(SPHINXAUTOBUILD) + add_doc_target( + ${name}-live + COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_MAKE_DIRS} + COMMAND ${CMAKE_COMMAND} -E env ${DOCSET_ENV} + ${SPHINXAUTOBUILD} + --watch ${DOCSET_CFG_DIR} + --ignore ${DOCSET_BUILD_DIR} + -b html + -c ${DOCSET_CFG_DIR} + -d ${DOCSET_DOCTREE_DIR} + -w ${DOCSET_BUILD_DIR}/html-live.log + ${SPHINXOPTS} + ${SPHINXOPTS_EXTRA} + ${DOCSET_SPHINXOPTS} + ${EXTRA_ARGS} + ${DOCSET_SRC_DIR} + ${DOCSET_HTML_DIR} + USES_TERMINAL + COMMENT "Building ${name}-live docset..." + ) + endif() + + add_custom_target( + ${name}-linkcheck + COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_MAKE_DIRS} + COMMAND ${CMAKE_COMMAND} -E env ${DOCSET_ENV} + ${SPHINXBUILD} + -b linkcheck + -c ${DOCSET_CFG_DIR} + -d ${DOCSET_DOCTREE_DIR} + -w ${DOCSET_BUILD_DIR}/linkcheck.log + ${SPHINXOPTS} + ${SPHINXOPTS_EXTRA} + ${DOCSET_SPHINXOPTS} + ${EXTRA_ARGS} + ${DOCSET_SRC_DIR} + ${DOCSET_LINKCHECK_DIR} + USES_TERMINAL + COMMENT "Checking links for ${name} docset..." + ) + + set_target_properties( + ${name} ${name}-all + ${name}-linkcheck + PROPERTIES + ADDITIONAL_CLEAN_FILES "${DOCSET_CLEAN_DIRS}" + ) + + if(SPHINXAUTOBUILD) + set_target_properties( + ${name}-live ${name}-live-all + PROPERTIES + ADDITIONAL_CLEAN_FILES "${DOCSET_CLEAN_DIRS}" + ) + endif() + + add_custom_target( + ${name}-clean + COMMAND ${CMAKE_COMMAND} -E rm -rf ${DOCSET_CLEAN_DIRS} + ) +endfunction() + +# 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: `` +# - Target 2 named: `-all` +# +# Both targets will produce same result, but target 1 is useful when only +# wanting to build a subset of the docs and missing references to other targets +# are acceptable (warnings will be generated). +# +# Target 2 is used for complete docset builds where it is important that build +# order of each target is under full control. +# +function(add_doc_target name) + add_custom_target(${name} ${ARGN}) + add_custom_target(${name}-all ${ARGN}) +endfunction() + +#------------------------------------------------------------------------------- +# Paths + +get_filename_component(NRFBM_BASE ${CMAKE_CURRENT_LIST_DIR}../ DIRECTORY) +get_filename_component(NRF_BASE ${CMAKE_CURRENT_LIST_DIR}../../nrf DIRECTORY) + +# HTML output directory +set(HTML_DIR ${CMAKE_BINARY_DIR}/html) +file(MAKE_DIRECTORY ${HTML_DIR}) + +#------------------------------------------------------------------------------- +# docset: nrfbm + +file(READ "${NRFBM_BASE}/VERSION" NRFBM_VERSION) +string(STRIP ${NRFBM_VERSION} NRFBM_VERSION) + +add_docset(nrfbm ${NRFBM_VERSION}) +add_doxygen_docset(nrfbm ${NRFBM_BASE} ${NRFBM_VERSION}) + +#------------------------------------------------------------------------------- +# docset: s115 + +add_doxygen_docset(s115 ${NRFBM_BASE} "9.0.0-3.prototype" STANDALONE) + +#------------------------------------------------------------------------------- +# docset: kconfig + +add_docset(kconfig "") + +#------------------------------------------------------------------------------- +# Global targets + +add_custom_target( + copy-extra-content + COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_LIST_DIR}/_static/html/index.html ${HTML_DIR} +) + +add_custom_target( + merge-search-indexes + COMMAND + ${PYTHON_EXECUTABLE} + ${NRF_BASE}/doc/_scripts/merge_search_indexes.py + -b ${CMAKE_BINARY_DIR} + COMMENT "Merging search indexes..." +) + +add_dependencies(merge-search-indexes + nrfbm-all + kconfig-all +) + +# Add dependencies to both a docset-all and docset-live-all targets if available +function(add_doc_dependencies docset) + add_dependencies(${docset}-all ${ARGN}) + if(SPHINXAUTOBUILD) + add_dependencies(${docset}-live-all ${ARGN}) + endif() +endfunction() + +add_doc_dependencies(nrfbm kconfig-all s115) + +add_custom_target(build-all ALL) +add_dependencies(build-all + copy-extra-content + merge-search-indexes + nrfbm-all + kconfig-all + s115 +) + +add_custom_target(linkcheck) +add_dependencies(linkcheck + nrfbm-linkcheck + kconfig-linkcheck +) diff --git a/doc/_static/html/index.html b/doc/_static/html/index.html index 1dc6d68854..2ba01dcd66 100644 --- a/doc/_static/html/index.html +++ b/doc/_static/html/index.html @@ -2,7 +2,7 @@ diff --git a/doc/_utils/redirects.py b/doc/_utils/redirects.py new file mode 100644 index 0000000000..8284a084c7 --- /dev/null +++ b/doc/_utils/redirects.py @@ -0,0 +1,25 @@ +""" +Copyright (c) 2025 Nordic Semiconductor +SPDX-License-Identifier: Apache-2.0 + +This module contains per-docset variables with a list of tuples +(old_url, newest_url) for pages that need a redirect. This list allows redirecting +old URLs (caused by, for example, reorganizing doc directories). + +Notes: + - Keep URLs relative to document root (NO leading slash and + without the html extension). + - Keep URLs in the order of pages from the doc hierarchy. Move entry order if hierarchy changes. + - Comments mention the page name; edit the comment when the page name changes. + - Each comment is valid for the line where it is added AND all lines without comment after it. + - If a page was removed, mention in the comment when it was removed, if possible. + A redirect should still point to another page. + +Examples: + ("old/README", "absolutely/newer/index"), # Name of the page + ("new/index", "absolutely/newer/index"), + ("even/newer/index", "absolutely/newer/index"), +""" + +NRFBM = [ +] diff --git a/doc/_utils/utils.py b/doc/_utils/utils.py new file mode 100644 index 0000000000..ffcf9b802e --- /dev/null +++ b/doc/_utils/utils.py @@ -0,0 +1,104 @@ +# +# Copyright (c) 2023 Nordic Semiconductor +# +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause +# + +from os import PathLike +from pathlib import Path +from typing import Tuple, Optional + +from sphinx.application import Sphinx +from sphinx.cmd.build import get_parser +from west.manifest import Manifest + + +_NRFBM_BASE = Path(__file__).parents[2] +"""nRF BM Repository root""" + +_MANIFEST = Manifest.from_file(_NRFBM_BASE / "west.yml") +"""Manifest instance""" + +ALL_DOCSETS = { + "nrfbm": ("nRF Connect SDK Bare Metal", "index", "manifest"), + "kconfig": ("Kconfig Reference", "index", None), +} +"""All supported docsets (name: title, home page, manifest project name).""" + + +def get_projdir(docset: str) -> Path: + """Obtain the project directory for the given docset. + + Args: + docset: Target docset. + + Returns: + Project path for the given docset. + """ + + name = ALL_DOCSETS[docset][2] + if not name: + raise ValueError("Given docset has no associated project") + + p = next((p for p in _MANIFEST.projects if p.name == name), None) + assert p, f"Project {name} not in manifest" + + return Path(p.topdir) / Path(p.path) + + +def get_builddir() -> PathLike: + """Obtain Sphinx base build directory for a given docset. + + Returns: + Base build path. + """ + parser = get_parser() + args = parser.parse_args() + return (Path(args.outputdir) / ".." / "..").resolve() + + +def get_outputdir(docset: str) -> PathLike: + """Obtain Sphinx output directory for a given docset. + + Args: + docset: Target docset. + + Returns: + Build path of the given docset. + """ + + return get_builddir() / "html" / docset + + +def get_srcdir(docset: str) -> PathLike: + """Obtain sources directory for a given docset. + + Args: + docset: Target docset. + + Returns: + Sources directory of the given docset. + """ + + return get_builddir() / docset / "src" + + +def get_intersphinx_mapping(docset: str) -> Optional[Tuple[str, str]]: # pylint: disable=unsubscriptable-object + """Obtain intersphinx configuration for a given docset. + + Args: + docset: Target docset. + + Notes: + Relative links are used for URL prefix. + + Returns: + Intersphinx configuration if available. + """ + + outputdir = get_outputdir(docset) + inventory = outputdir / "objects.inv" + if not inventory.exists(): + return + + return (str(Path("..") / docset), str(inventory)) diff --git a/doc/kconfig/conf.py b/doc/kconfig/conf.py new file mode 100644 index 0000000000..180f039b3d --- /dev/null +++ b/doc/kconfig/conf.py @@ -0,0 +1,67 @@ +# Copyright (c) 2025 Nordic Semiconductor +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + +import os +from pathlib import Path +import sys + + +# Paths ------------------------------------------------------------------------ + +NRFBM_BASE = Path(__file__).absolute().parents[2] + +sys.path.insert(0, str(NRFBM_BASE / "doc" / "_utils")) +import utils + +ZEPHYR_BASE = NRFBM_BASE / ".." / "zephyr" +NRF_BASE = NRFBM_BASE / ".." / "nrf" + +# General configuration -------------------------------------------------------- + +project = "Kconfig reference" +copyright = "2025, Nordic Semiconductor" +author = "Nordic Semiconductor" +# NOTE: use blank space as version to preserve space +version = " " + +sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_extensions")) + +extensions = ["zephyr.kconfig", "zephyr.external_content"] + +# Options for HTML output ------------------------------------------------------ + +html_theme = "sphinx_ncs_theme" +html_static_path = [str(NRFBM_BASE / "doc" / "_static")] +html_title = project +html_last_updated_fmt = "%b %d, %Y" +html_show_sourcelink = True +html_show_sphinx = False + +html_theme_options = { + "docset": "kconfig", "docsets": utils.ALL_DOCSETS, + "prev_next_buttons_location": None +} + +# Options for external_content ------------------------------------------------- + +external_content_contents = [ + (NRFBM_BASE / "doc" / "kconfig", "*.rst"), +] + +# Options for zephyr.kconfig ----------------------------------------------------- + +kconfig_generate_db = True +kconfig_ext_paths = [ZEPHYR_BASE, NRF_BASE, NRFBM_BASE] + +# Adding NCS_ specific entries. Can be removed when the NCSDK-14227 improvement +# task has been completed. +os.environ["NCS_MEMFAULT_FIRMWARE_SDK_KCONFIG"] = str( + NRF_BASE + / "modules" + / "memfault-firmware-sdk" + / "Kconfig" +) + +# FIXME: should be automatically added +os.environ["ZEPHYR_NRF_MODULE_DIR"] = str(NRF_BASE) +os.environ["ZEPHYR_NRF_BM_MODULE_DIR"] = str(NRFBM_BASE) diff --git a/doc/kconfig/index.rst b/doc/kconfig/index.rst new file mode 100644 index 0000000000..13e8bbad96 --- /dev/null +++ b/doc/kconfig/index.rst @@ -0,0 +1,24 @@ +.. _configuration_options: +.. _kconfig-search: + +Kconfig search +############## + + +:file:`Kconfig` files describe build-time configuration options (called symbols in Kconfig-speak), how they are grouped into menus and sub-menus, and dependencies between them that determine what configurations are valid. +:file:`Kconfig` files appear throughout the directory tree. +For example, :file:`subsys/pm/Kconfig` defines power-related options. + +All Kconfig options can be searched using the search functionality. +The search functionality supports searching using regular expressions. +See :ref:`kconfig_regex` for more information. +All the Kconfig options that match a particular regular expression is displayed along with the information on the matched Kconfig options. +The search results can be navigated page by page if the number of matches exceeds a page. + +.. kconfig:search:: + +.. toctree:: + :maxdepth: 1 + :hidden: + + regex diff --git a/doc/kconfig/regex.rst b/doc/kconfig/regex.rst new file mode 100644 index 0000000000..5ee3dfb5e8 --- /dev/null +++ b/doc/kconfig/regex.rst @@ -0,0 +1,14 @@ +.. _kconfig_regex: + +Regex tips and tricks +##################### + +Following are some of the useful JavaScript-based Regex patterns that can be used while searching the configuration options: + +* ``.*`` - To search for zero or more occurrences of the string that follows the special character combination. +* ``\d`` - To search for any digit. Equivalent to ``[0-9]``. For example, ``\d`` or ``[0-9]`` matches ``6`` in ``IPV6``. +* ``^...$`` - To search for a string of finite length, starting and ending with definite characters. For example, ``^c....._m...m$`` matches :Kconfig:option:`CONFIG_MODEM`. + +For more information, see `Regular expression syntax cheatsheet`_. + +.. _`Regular expression syntax cheatsheet`: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions/Cheatsheet diff --git a/doc/nrf-bm/conf.py b/doc/nrf-bm/conf.py deleted file mode 100644 index bf87d8820c..0000000000 --- a/doc/nrf-bm/conf.py +++ /dev/null @@ -1,67 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = 'nRF Connect SDK Bare Metal option - 0.9.99' -copyright = '2025, Nordic Semiconductor' -author = 'Nordic Semiconductor' - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.intersphinx', 'sphinx_tabs.tabs', 'breathe'] - -rst_epilog = """ -.. include:: /substitutions.txt -.. include:: /links.txt -.. include:: /shortcuts.txt -""" - -# Options for breathe --------------------------------------------------------- -breathe_projects = { - "nRF Connect SDK Bare Metal option API": "doxygen/nrf-bm_api_xml/", -} -breathe_default_project = "nRF Connect SDK Bare Metal option API" -breathe_domain_by_extension = {"h": "c", "c": "c"} -breathe_separate_member_pages = True - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The root document. -root_doc = 'index' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ["venv"] - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static', 'pdfs'] diff --git a/doc/nrf-bm/gen_docs.py b/doc/nrf-bm/gen_docs.py deleted file mode 100644 index 84ba89013a..0000000000 --- a/doc/nrf-bm/gen_docs.py +++ /dev/null @@ -1,147 +0,0 @@ -import os -import shutil -from subprocess import call - -# Define the paths -script_dir = os.path.dirname(os.path.abspath(__file__)) # Directory where the script is located -source_dir = os.path.abspath("_build/source") -samples_dir = os.path.abspath("../../samples") -static_dir = os.path.abspath("../_static") # Path to the _static directory -requirements_path = os.path.join(script_dir, "requirements.txt") # Path to the requirements.txt file -includes_dir = os.path.join(script_dir, "includes") # Path to the includes directory -sample_dir = os.path.join(script_dir, "sample") # Path to the sample directory -pdf_source_dir = os.path.abspath('../../components/softdevice/s115/') # Path to the PDF source directory -pdf_destination_dir = os.path.join(source_dir, 'pdfs') # Destination directory within _static -images_dir = os.path.join(script_dir, "images") # Path to the images directory -softdevice_rst_source = os.path.abspath('../../components/softdevice/s115/doc') - -# Install packages from requirements.txt -if os.path.exists(requirements_path): - print("Installing packages from requirements.txt...") - call(["pip", "install", "-r", requirements_path]) -else: - print("requirements.txt not found.") - exit() - -# Create the source directory if it doesn't exist -os.makedirs(source_dir, exist_ok=True) -os.makedirs(pdf_destination_dir, exist_ok=True) - -# Copy RST files and maintain directory structure -for root, dirs, files in os.walk(".", topdown=True): - # Exclude the source directory from the search - dirs[:] = [d for d in dirs if os.path.abspath(os.path.join(root, d)) != source_dir] - for file in files: - if file.endswith(".rst"): - src_file_path = os.path.join(root, file) - relative_path = os.path.relpath(root, ".") - dest_dir = os.path.join(source_dir, relative_path) - os.makedirs(dest_dir, exist_ok=True) - shutil.copy2(src_file_path, dest_dir) - -# Copy PDFs -if os.path.exists(pdf_source_dir): - for file in os.listdir(pdf_source_dir): - if file.endswith(".pdf"): - src_file_path = os.path.join(pdf_source_dir, file) - shutil.copy2(src_file_path, pdf_destination_dir) - print(f"Copied PDFs to {pdf_destination_dir}") -else: - print("PDF source directory not found.") - exit() - -# Copy sample READMEs -if os.path.exists(samples_dir): - for root, dirs, files in os.walk(samples_dir): - for file in files: - if file == "README.rst": - relative_dir = os.path.relpath(root, samples_dir) - dest_dir = os.path.join(source_dir, "samples", relative_dir) - os.makedirs(dest_dir, exist_ok=True) - shutil.copy2(os.path.join(root, file), dest_dir) - -# Copy SoftDevice RST files to the _build/source directory -for file_name in os.listdir(softdevice_rst_source): - if file_name.endswith('.rst'): - src_file_path = os.path.join(softdevice_rst_source, file_name) - shutil.copy2(src_file_path, source_dir) - print(f"Copied {file_name} to {source_dir}") - -# Copy the _static directory -dest_static_dir = os.path.join(source_dir, "_static") -if os.path.exists(dest_static_dir): - shutil.rmtree(dest_static_dir) # Remove the existing directory if it exists -shutil.copytree(static_dir, dest_static_dir) - -# Copy the includes directory -if os.path.exists(includes_dir): - dest_includes_dir = os.path.join(source_dir, "includes") - if os.path.exists(dest_includes_dir): - shutil.rmtree(dest_includes_dir) # Remove the existing directory if it exists - shutil.copytree(includes_dir, dest_includes_dir) -else: - print("includes directory not found.") - exit() - -# Copy the images directory -if os.path.exists(images_dir): - dest_images_dir = os.path.join(source_dir, "images") - if os.path.exists(dest_images_dir): - shutil.rmtree(dest_images_dir) # Remove the existing directory if it exists - shutil.copytree(images_dir, dest_images_dir) -else: - print("images directory not found.") - exit() - -# Copy Sphinx configuration file and other text files -conf_path = os.path.join(script_dir, "conf.py") -links_path = os.path.join(script_dir, "links.txt") -substitutions_path = os.path.join(script_dir, "substitutions.txt") -shortcuts_path = os.path.join(script_dir, "shortcuts.txt") - -for file_path in [conf_path, links_path, substitutions_path, shortcuts_path]: - if os.path.exists(file_path): - shutil.copy2(file_path, source_dir) - else: - print(f"File not found: {file_path}") - exit() - -# Prepare Doxygen XML output for Breathe - -# Save the current directory -original_dir = os.getcwd() - -# Path to the Doxyfile -doxyfile_dir = os.path.abspath('doxygen') -doxyfile_path = os.path.join(doxyfile_dir, 'nrf-bm.doxyfile') - -# Change to the directory containing the Doxyfile -os.chdir(doxyfile_dir) - -# Run Doxygen -print("Running Doxygen...") -call(['doxygen', 'nrf-bm.doxyfile']) - -# Change back to the original directory -os.chdir(original_dir) - -# Path to the Doxygen output directory -doxygen_output_dir = os.path.abspath('doxygen/doxygen/nrf-bm_api_xml') - -# Destination directory for Doxygen XML files within the Sphinx source -doxygen_dest_dir = os.path.join(source_dir, 'doxygen/nrf-bm_api_xml') - -# Copy Doxygen XML output to the Sphinx source directory -if os.path.exists(doxygen_output_dir): - if os.path.exists(doxygen_dest_dir): - shutil.rmtree(doxygen_dest_dir) # Remove the existing directory if it exists - shutil.copytree(doxygen_output_dir, doxygen_dest_dir) - print(f"Copied Doxygen XML files to {doxygen_dest_dir}") -else: - print("Doxygen output directory not found.") - exit() - -# Run Sphinx -call(["sphinx-build", "-b", "html", source_dir, "_build/html"]) - -print("Build finished. The HTML pages are in _build/html.") diff --git a/doc/nrf-bm/requirements.txt b/doc/nrf-bm/requirements.txt deleted file mode 100644 index e5b53e529d..0000000000 --- a/doc/nrf-bm/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -Sphinx -sphinx_rtd_theme -sphinx-tabs>=3.4 -sphinx-togglebutton -Breathe diff --git a/doc/nrf-bm/README.md b/doc/nrfbm/README.md similarity index 100% rename from doc/nrf-bm/README.md rename to doc/nrfbm/README.md diff --git a/doc/nrf-bm/api/api.rst b/doc/nrfbm/api/api.rst similarity index 81% rename from doc/nrf-bm/api/api.rst rename to doc/nrfbm/api/api.rst index 71b34db319..189b77a609 100644 --- a/doc/nrf-bm/api/api.rst +++ b/doc/nrfbm/api/api.rst @@ -16,15 +16,11 @@ Bluetooth LE Advertising library ================================ .. doxygengroup:: ble_adv - :inner: - :members: Advertising and Scan Response Data Encoder ------------------------------------------ .. doxygengroup:: ble_sdk_lib_advdata - :inner: - :members: .. _api_ble_conn_params: @@ -32,8 +28,6 @@ Bluetooth LE Connection Parameter library ========================================= .. doxygengroup:: ble_conn_params - :inner: - :members: .. _api_ble_conn_state: @@ -41,50 +35,36 @@ Bluetooth LE Connection State library ===================================== .. doxygengroup:: ble_conn_state - :inner: - :members: Bare Metal Buttons library ========================== .. doxygengroup:: bm_buttons - :inner: - :members: Bare Metal Event Scheduler library ================================== .. doxygengroup:: event_scheduler - :inner: - :members: Bare Metal Low Power UART with EasyDMA driver ============================================= .. doxygengroup:: bm_lpuarte - :inner: - :members: Bare Metal Storage library ========================== .. doxygengroup:: bm_storage - :inner: - :members: Bare Metal Storage library backend ---------------------------------- .. doxygengroup:: bm_storage_backend - :inner: - :members: Bare Metal Timer library ======================== .. doxygengroup:: bm_timer - :inner: - :members: .. _api_ble_bm_zms: @@ -92,15 +72,11 @@ Bare Metal Zephyr Memory Storage (ZMS) ====================================== .. doxygengroup:: bm_zms - :inner: - :members: GATT Queue ========== .. doxygengroup:: ble_gq - :inner: - :members: .. _api_peer_manager: @@ -108,29 +84,21 @@ Peer Manager library ==================== .. doxygengroup:: peer_manager - :inner: - :members: Queued Writes module ==================== .. doxygengroup:: ble_qwr - :inner: - :members: Record Access Control Point =========================== .. doxygengroup:: ble_racp - :inner: - :members: Sensor data simulator library ============================= .. doxygengroup:: sensorsim - :inner: - :members: Services ******** @@ -141,8 +109,6 @@ Battery Service =============== .. doxygengroup:: ble_bas - :inner: - :members: .. _api_ble_cgms: @@ -150,8 +116,6 @@ Continuous Glucose Monitoring Service ===================================== .. doxygengroup:: ble_cgms - :inner: - :members: .. _api_dis: @@ -159,8 +123,6 @@ Device Information Service ========================== .. doxygengroup:: ble_dis - :inner: - :members: .. _api_ble_hrs: @@ -168,8 +130,6 @@ Heart Rate Service ================== .. doxygengroup:: ble_hrs - :inner: - :members: .. _api_human_interface_device_service: @@ -177,8 +137,6 @@ Human Interface Device Service ============================== .. doxygengroup:: ble_hids - :inner: - :members: .. _api_lbs: @@ -186,8 +144,6 @@ LED Button Service ================== .. doxygengroup:: ble_lbs - :inner: - :members: .. _api_mcu_manager_service: @@ -195,8 +151,6 @@ MCU manager Service (MCUmgr) ============================ .. doxygengroup:: ble_mcumgr - :inner: - :members: .. _api_ble_nus: @@ -204,15 +158,11 @@ Nordic UART Service (NUS) ========================= .. doxygengroup:: ble_nus - :inner: - :members: SoftDevice Handler ****************** .. doxygengroup:: nrf_sdh - :inner: - :members: Utils ***** @@ -221,26 +171,18 @@ nRF Error Codes =============== .. doxygengroup:: nrf_error - :inner: - :members: Service UUID definitions ======================== .. doxygengroup:: UUID_SERVICES - :inner: - :members: Characteristic UUID definitions =============================== .. doxygengroup:: UUID_CHARACTERISTICS - :inner: - :members: Bluetooth LE Date Time characteristic type ========================================== .. doxygengroup:: ble_sdk_srv_date_time - :inner: - :members: diff --git a/doc/nrf-bm/app_dev/dfu/bootloader_keys.rst b/doc/nrfbm/app_dev/dfu/bootloader_keys.rst similarity index 100% rename from doc/nrf-bm/app_dev/dfu/bootloader_keys.rst rename to doc/nrfbm/app_dev/dfu/bootloader_keys.rst diff --git a/doc/nrf-bm/app_dev/dfu/index.rst b/doc/nrfbm/app_dev/dfu/index.rst similarity index 100% rename from doc/nrf-bm/app_dev/dfu/index.rst rename to doc/nrfbm/app_dev/dfu/index.rst diff --git a/doc/nrf-bm/app_dev/dfu/memory_partitioning.rst b/doc/nrfbm/app_dev/dfu/memory_partitioning.rst similarity index 100% rename from doc/nrf-bm/app_dev/dfu/memory_partitioning.rst rename to doc/nrfbm/app_dev/dfu/memory_partitioning.rst diff --git a/doc/nrf-bm/app_dev/dfu/single_bank_dfu.rst b/doc/nrfbm/app_dev/dfu/single_bank_dfu.rst similarity index 100% rename from doc/nrf-bm/app_dev/dfu/single_bank_dfu.rst rename to doc/nrfbm/app_dev/dfu/single_bank_dfu.rst diff --git a/doc/nrf-bm/app_dev/dfu/ug_dfu.rst b/doc/nrfbm/app_dev/dfu/ug_dfu.rst similarity index 100% rename from doc/nrf-bm/app_dev/dfu/ug_dfu.rst rename to doc/nrfbm/app_dev/dfu/ug_dfu.rst diff --git a/doc/nrfbm/conf.py b/doc/nrfbm/conf.py new file mode 100644 index 0000000000..1285b99e40 --- /dev/null +++ b/doc/nrfbm/conf.py @@ -0,0 +1,100 @@ +# Copyright (c) 2025 Nordic Semiconductor +# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause + +import os +from pathlib import Path +import sys + + +# Paths ------------------------------------------------------------------------ + +NRFBM_BASE = Path(__file__).absolute().parents[2] + +sys.path.insert(0, str(NRFBM_BASE / "doc" / "_utils")) +import redirects +import utils + +ZEPHYR_BASE = NRFBM_BASE / ".." / "zephyr" + +# General configuration -------------------------------------------------------- + +project = "nRF Connect SDK Bare Metal" +copyright = "2025, Nordic Semiconductor" +author = "Nordic Semiconductor" +version = release = os.environ.get("DOCSET_VERSION") + +sys.path.insert(0, str(ZEPHYR_BASE / "doc" / "_extensions")) + +extensions = [ + "zephyr.html_redirects", + "zephyr.kconfig", + "zephyr.external_content", + "zephyr.doxyrunner", + "zephyr.doxybridge", + "sphinx_tabs.tabs", + "sphinx_togglebutton", + "sphinx_copybutton", + "sphinx.ext.intersphinx", +] + +rst_epilog = """ +.. include:: /substitutions.txt +.. include:: /links.txt +.. include:: /shortcuts.txt +""" + +# -- Options for HTML output ------------------------------------------------- + +html_theme = "sphinx_ncs_theme" +html_static_path = [str(NRFBM_BASE / "doc" / "_static")] +html_last_updated_fmt = "%b %d, %Y" +html_show_sourcelink = True +html_show_sphinx = False + +html_theme_options = {"docset": "nrfbm", "docsets": utils.ALL_DOCSETS} + +# Options for intersphinx ------------------------------------------------------ + +intersphinx_mapping = dict() + +kconfig_mapping = utils.get_intersphinx_mapping("kconfig") +if kconfig_mapping: + intersphinx_mapping["kconfig"] = kconfig_mapping + +# Options for external_content ------------------------------------------------- + +external_content_contents = [ + (NRFBM_BASE / "doc" / "nrfbm", "*"), + (NRFBM_BASE, "samples/**/*.rst"), +] + +external_content_keep = ["versions.txt"] +# -- Options for doxyrunner plugin --------------------------------------------- + +_doxyrunner_outdir = utils.get_builddir() / "html" / "nrfbm" / "doxygen" + +doxyrunner_doxygen = os.environ.get("DOXYGEN_EXECUTABLE", "doxygen") +doxyrunner_projects = { + "nrf": { + "doxyfile": NRFBM_BASE / "doc" / "nrfbm" / "nrfbm.doxyfile.in", + "outdir": _doxyrunner_outdir, + "fmt": True, + "fmt_vars": { + "NRFBM_BASE": str(NRFBM_BASE), + "DOCSET_SOURCE_BASE": str(NRFBM_BASE), + "DOCSET_BUILD_DIR": str(_doxyrunner_outdir), + "DOCSET_VERSION": version, + } + } +} + +# -- Options for doxybridge plugin --------------------------------------------- + +doxybridge_projects = { + "nrfbm": _doxyrunner_outdir, + "s115": utils.get_builddir() / "html" / "s115", +} + +# Options for html_redirect ---------------------------------------------------- + +html_redirect_pages = redirects.NRFBM diff --git a/doc/nrf-bm/doxygen/mainpage.dox b/doc/nrfbm/doxygen/mainpage.dox similarity index 100% rename from doc/nrf-bm/doxygen/mainpage.dox rename to doc/nrfbm/doxygen/mainpage.dox diff --git a/doc/nrf-bm/drivers.rst b/doc/nrfbm/drivers.rst similarity index 100% rename from doc/nrf-bm/drivers.rst rename to doc/nrfbm/drivers.rst diff --git a/doc/nrf-bm/drivers/lpuarte.rst b/doc/nrfbm/drivers/lpuarte.rst similarity index 100% rename from doc/nrf-bm/drivers/lpuarte.rst rename to doc/nrfbm/drivers/lpuarte.rst diff --git a/doc/nrf-bm/images/add_build_configuration.png b/doc/nrfbm/images/add_build_configuration.png similarity index 100% rename from doc/nrf-bm/images/add_build_configuration.png rename to doc/nrfbm/images/add_build_configuration.png diff --git a/doc/nrf-bm/images/add_build_configuration_page.png b/doc/nrfbm/images/add_build_configuration_page.png similarity index 100% rename from doc/nrf-bm/images/add_build_configuration_page.png rename to doc/nrfbm/images/add_build_configuration_page.png diff --git a/doc/nrf-bm/images/board_target.png b/doc/nrfbm/images/board_target.png similarity index 100% rename from doc/nrf-bm/images/board_target.png rename to doc/nrfbm/images/board_target.png diff --git a/doc/nrf-bm/images/create_new_application_from_sample_quick_pick_menu.png b/doc/nrfbm/images/create_new_application_from_sample_quick_pick_menu.png similarity index 100% rename from doc/nrf-bm/images/create_new_application_from_sample_quick_pick_menu.png rename to doc/nrfbm/images/create_new_application_from_sample_quick_pick_menu.png diff --git a/doc/nrf-bm/images/dfu_softdevice.svg b/doc/nrfbm/images/dfu_softdevice.svg similarity index 100% rename from doc/nrf-bm/images/dfu_softdevice.svg rename to doc/nrfbm/images/dfu_softdevice.svg diff --git a/doc/nrf-bm/images/dfu_steps_sd_fwl.svg b/doc/nrfbm/images/dfu_steps_sd_fwl.svg similarity index 100% rename from doc/nrf-bm/images/dfu_steps_sd_fwl.svg rename to doc/nrfbm/images/dfu_steps_sd_fwl.svg diff --git a/doc/nrf-bm/images/image_header_tlv.svg b/doc/nrfbm/images/image_header_tlv.svg similarity index 100% rename from doc/nrf-bm/images/image_header_tlv.svg rename to doc/nrfbm/images/image_header_tlv.svg diff --git a/doc/nrf-bm/images/nrf5_bm_memory_part.svg b/doc/nrfbm/images/nrf5_bm_memory_part.svg similarity index 100% rename from doc/nrf-bm/images/nrf5_bm_memory_part.svg rename to doc/nrfbm/images/nrf5_bm_memory_part.svg diff --git a/doc/nrf-bm/images/partition_RRAM.svg b/doc/nrfbm/images/partition_RRAM.svg similarity index 100% rename from doc/nrf-bm/images/partition_RRAM.svg rename to doc/nrfbm/images/partition_RRAM.svg diff --git a/doc/nrf-bm/images/show_build_configuration_files.png b/doc/nrfbm/images/show_build_configuration_files.png similarity index 100% rename from doc/nrf-bm/images/show_build_configuration_files.png rename to doc/nrfbm/images/show_build_configuration_files.png diff --git a/doc/nrf-bm/images/show_build_configuration_files_mcuboot.png b/doc/nrfbm/images/show_build_configuration_files_mcuboot.png similarity index 100% rename from doc/nrf-bm/images/show_build_configuration_files_mcuboot.png rename to doc/nrfbm/images/show_build_configuration_files_mcuboot.png diff --git a/doc/nrf-bm/images/single_bank_dfu_steps.svg b/doc/nrfbm/images/single_bank_dfu_steps.svg similarity index 100% rename from doc/nrf-bm/images/single_bank_dfu_steps.svg rename to doc/nrfbm/images/single_bank_dfu_steps.svg diff --git a/doc/nrf-bm/includes/configure_and_build_sample.txt b/doc/nrfbm/includes/configure_and_build_sample.txt similarity index 100% rename from doc/nrf-bm/includes/configure_and_build_sample.txt rename to doc/nrfbm/includes/configure_and_build_sample.txt diff --git a/doc/nrf-bm/includes/create_sample.txt b/doc/nrfbm/includes/create_sample.txt similarity index 100% rename from doc/nrf-bm/includes/create_sample.txt rename to doc/nrfbm/includes/create_sample.txt diff --git a/doc/nrf-bm/includes/program_sample.txt b/doc/nrfbm/includes/program_sample.txt similarity index 100% rename from doc/nrf-bm/includes/program_sample.txt rename to doc/nrfbm/includes/program_sample.txt diff --git a/doc/nrf-bm/includes/softdevice_flash.txt b/doc/nrfbm/includes/softdevice_flash.txt similarity index 100% rename from doc/nrf-bm/includes/softdevice_flash.txt rename to doc/nrfbm/includes/softdevice_flash.txt diff --git a/doc/nrf-bm/index.rst b/doc/nrfbm/index.rst similarity index 100% rename from doc/nrf-bm/index.rst rename to doc/nrfbm/index.rst diff --git a/doc/nrf-bm/install_nrf_bm.rst b/doc/nrfbm/install_nrf_bm.rst similarity index 100% rename from doc/nrf-bm/install_nrf_bm.rst rename to doc/nrfbm/install_nrf_bm.rst diff --git a/doc/nrf-bm/libraries/bluetooth/ble_conn_params.rst b/doc/nrfbm/libraries/bluetooth/ble_conn_params.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/ble_conn_params.rst rename to doc/nrfbm/libraries/bluetooth/ble_conn_params.rst diff --git a/doc/nrf-bm/libraries/bluetooth/index.rst b/doc/nrfbm/libraries/bluetooth/index.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/index.rst rename to doc/nrfbm/libraries/bluetooth/index.rst diff --git a/doc/nrf-bm/libraries/bluetooth/peer_manager.rst b/doc/nrfbm/libraries/bluetooth/peer_manager.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/peer_manager.rst rename to doc/nrfbm/libraries/bluetooth/peer_manager.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_bas.rst b/doc/nrfbm/libraries/bluetooth/services/ble_bas.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_bas.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_bas.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_cgms.rst b/doc/nrfbm/libraries/bluetooth/services/ble_cgms.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_cgms.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_cgms.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_dis.rst b/doc/nrfbm/libraries/bluetooth/services/ble_dis.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_dis.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_dis.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_hids.rst b/doc/nrfbm/libraries/bluetooth/services/ble_hids.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_hids.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_hids.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_hrs.rst b/doc/nrfbm/libraries/bluetooth/services/ble_hrs.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_hrs.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_hrs.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_lbs.rst b/doc/nrfbm/libraries/bluetooth/services/ble_lbs.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_lbs.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_lbs.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_mcumgr.rst b/doc/nrfbm/libraries/bluetooth/services/ble_mcumgr.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_mcumgr.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_mcumgr.rst diff --git a/doc/nrf-bm/libraries/bluetooth/services/ble_nus.rst b/doc/nrfbm/libraries/bluetooth/services/ble_nus.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/services/ble_nus.rst rename to doc/nrfbm/libraries/bluetooth/services/ble_nus.rst diff --git a/doc/nrf-bm/libraries/bm_zms.rst b/doc/nrfbm/libraries/bm_zms.rst similarity index 100% rename from doc/nrf-bm/libraries/bm_zms.rst rename to doc/nrfbm/libraries/bm_zms.rst diff --git a/doc/nrf-bm/libraries/index.rst b/doc/nrfbm/libraries/index.rst similarity index 100% rename from doc/nrf-bm/libraries/index.rst rename to doc/nrfbm/libraries/index.rst diff --git a/doc/nrf-bm/links.txt b/doc/nrfbm/links.txt similarity index 100% rename from doc/nrf-bm/links.txt rename to doc/nrfbm/links.txt diff --git a/doc/nrf-bm/migration/nrf5_bm_migration.rst b/doc/nrfbm/migration/nrf5_bm_migration.rst similarity index 100% rename from doc/nrf-bm/migration/nrf5_bm_migration.rst rename to doc/nrfbm/migration/nrf5_bm_migration.rst diff --git a/doc/nrf-bm/doxygen/nrf-bm.doxyfile b/doc/nrfbm/nrfbm.doxyfile.in similarity index 98% rename from doc/nrf-bm/doxygen/nrf-bm.doxyfile rename to doc/nrfbm/nrfbm.doxyfile.in index 364200fbd2..7a9f5b6e85 100644 --- a/doc/nrf-bm/doxygen/nrf-bm.doxyfile +++ b/doc/nrfbm/nrfbm.doxyfile.in @@ -42,13 +42,13 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "nRF Connect SDK Bare Metal option API" +PROJECT_NAME = "nRF Connect SDK Bare Metal API" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 0.8.0 +PROJECT_NUMBER = @DOCSET_VERSION@ # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -61,7 +61,7 @@ PROJECT_BRIEF = # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = ../../_doxygen/logo.png +PROJECT_LOGO = @NRFBM_BASE@/doc/_doxygen/logo.png # With the PROJECT_ICON tag one can specify an icon that is included in the tabs # when the HTML document is shown. Doxygen will copy the logo to the output @@ -74,7 +74,7 @@ PROJECT_ICON = # entered, it will be relative to the location where Doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = doxygen +OUTPUT_DIRECTORY = @DOCSET_BUILD_DIR@ # If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -180,7 +180,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where Doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = ../../../ +STRIP_FROM_PATH = @DOCSET_SOURCE_BASE@ # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -279,7 +279,13 @@ TAB_SIZE = 8 # with the commands \{ and \} for these it is advised to use the version @{ and # @} or use a double escape (\\{ and \\}) -ALIASES = +ALIASES = events="
Events generated
" \ + event{1}="" \ + event{2}="" \ + endevents="
\1
\1\2
" \ + mscs="
Relevant Message Sequence Charts
" \ + mmsc{1}="" \ + endmscs="
\1
" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For @@ -955,10 +961,8 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../../include/ \ - ../../../include/bluetooth/services \ - ../../../include/bluetooth/peer_manager \ - mainpage.dox +INPUT = @DOCSET_SOURCE_BASE@/include \ + @DOCSET_SOURCE_BASE@/doc/nrfbm/doxygen/mainpage.dox # This tag can be used to specify the character encoding of the source files # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses @@ -1285,7 +1289,7 @@ HTML_FILE_EXTENSION = .html # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_HEADER = ../../_doxygen/header.html +HTML_HEADER = @NRFBM_BASE@/doc/_doxygen/header.html # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank Doxygen will generate a standard @@ -1325,7 +1329,7 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = ../../_doxygen/doxygen-awesome.css +HTML_EXTRA_STYLESHEET = @NRFBM_BASE@/doc/_doxygen/doxygen-awesome.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1335,9 +1339,10 @@ HTML_EXTRA_STYLESHEET = ../../_doxygen/doxygen-awesome.css # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_FILES = ../../_doxygen/doxygen-awesome-darkmode-toggle.js \ - ../../_doxygen/doxygen-awesome-paragraph-link.js \ - ../../_doxygen/doxygen-awesome-interactive-toc.js +HTML_EXTRA_FILES = @NRFBM_BASE@/doc/_doxygen/doxygen-awesome-darkmode-toggle.js \ + @NRFBM_BASE@/doc/_doxygen/doxygen-awesome-fragment-copy-button.js \ + @NRFBM_BASE@/doc/_doxygen/doxygen-awesome-paragraph-link.js \ + @NRFBM_BASE@/doc/_doxygen/doxygen-awesome-interactive-toc.js # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output # should be rendered with a dark or light theme. @@ -2224,7 +2229,7 @@ GENERATE_XML = YES # The default directory is: xml. # This tag requires that the tag GENERATE_XML is set to YES. -XML_OUTPUT = nrf-bm_api_xml +XML_OUTPUT = xml # If the XML_PROGRAMLISTING tag is set to YES, Doxygen will dump the program # listings (including syntax highlighting and cross-referencing information) to @@ -2828,5 +2833,3 @@ MSCGEN_TOOL = # command). MSCFILE_DIRS = - -@INCLUDE = ../../_doxygen/aliases.doxyfile diff --git a/doc/nrf-bm/release_notes.rst b/doc/nrfbm/release_notes.rst similarity index 100% rename from doc/nrf-bm/release_notes.rst rename to doc/nrfbm/release_notes.rst diff --git a/doc/nrf-bm/release_notes/release_notes_0.1.0.rst b/doc/nrfbm/release_notes/release_notes_0.1.0.rst similarity index 100% rename from doc/nrf-bm/release_notes/release_notes_0.1.0.rst rename to doc/nrfbm/release_notes/release_notes_0.1.0.rst diff --git a/doc/nrf-bm/release_notes/release_notes_0.7.0.rst b/doc/nrfbm/release_notes/release_notes_0.7.0.rst similarity index 100% rename from doc/nrf-bm/release_notes/release_notes_0.7.0.rst rename to doc/nrfbm/release_notes/release_notes_0.7.0.rst diff --git a/doc/nrf-bm/release_notes/release_notes_0.8.0.rst b/doc/nrfbm/release_notes/release_notes_0.8.0.rst similarity index 100% rename from doc/nrf-bm/release_notes/release_notes_0.8.0.rst rename to doc/nrfbm/release_notes/release_notes_0.8.0.rst diff --git a/doc/nrf-bm/release_notes/release_notes_0.9.0.rst b/doc/nrfbm/release_notes/release_notes_0.9.0.rst similarity index 100% rename from doc/nrf-bm/release_notes/release_notes_0.9.0.rst rename to doc/nrfbm/release_notes/release_notes_0.9.0.rst diff --git a/doc/nrf-bm/release_notes/release_notes_changelog.rst b/doc/nrfbm/release_notes/release_notes_changelog.rst similarity index 100% rename from doc/nrf-bm/release_notes/release_notes_changelog.rst rename to doc/nrfbm/release_notes/release_notes_changelog.rst diff --git a/doc/nrf-bm/s115_docs.rst b/doc/nrfbm/s115_docs.rst similarity index 100% rename from doc/nrf-bm/s115_docs.rst rename to doc/nrfbm/s115_docs.rst diff --git a/doc/nrf-bm/sample/ble.rst b/doc/nrfbm/sample/ble.rst similarity index 100% rename from doc/nrf-bm/sample/ble.rst rename to doc/nrfbm/sample/ble.rst diff --git a/doc/nrf-bm/sample/dfu.rst b/doc/nrfbm/sample/dfu.rst similarity index 100% rename from doc/nrf-bm/sample/dfu.rst rename to doc/nrfbm/sample/dfu.rst diff --git a/doc/nrf-bm/sample/peripheral.rst b/doc/nrfbm/sample/peripheral.rst similarity index 100% rename from doc/nrf-bm/sample/peripheral.rst rename to doc/nrfbm/sample/peripheral.rst diff --git a/doc/nrf-bm/samples.rst b/doc/nrfbm/samples.rst similarity index 100% rename from doc/nrf-bm/samples.rst rename to doc/nrfbm/samples.rst diff --git a/doc/nrf-bm/shortcuts.txt b/doc/nrfbm/shortcuts.txt similarity index 100% rename from doc/nrf-bm/shortcuts.txt rename to doc/nrfbm/shortcuts.txt diff --git a/doc/nrf-bm/substitutions.txt b/doc/nrfbm/substitutions.txt similarity index 100% rename from doc/nrf-bm/substitutions.txt rename to doc/nrfbm/substitutions.txt diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 0000000000..0ca4c3a13e --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,7 @@ +doxmlparser +Sphinx>=8.1,<8.2 +sphinx-copybutton +sphinx-tabs +sphinx-togglebutton +sphinx-ncs-theme<1.1 +west diff --git a/doc/s115/s115_mainpage.dox b/doc/s115/mainpage.dox similarity index 100% rename from doc/s115/s115_mainpage.dox rename to doc/s115/mainpage.dox diff --git a/doc/s115/s115.doxyfile b/doc/s115/s115.doxyfile.in similarity index 99% rename from doc/s115/s115.doxyfile rename to doc/s115/s115.doxyfile.in index e9bf935125..cb7d027a73 100644 --- a/doc/s115/s115.doxyfile +++ b/doc/s115/s115.doxyfile.in @@ -48,7 +48,7 @@ PROJECT_NAME = "S115 SoftDevice API documentation" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 9.0.0-3.prototype +PROJECT_NUMBER = @DOCSET_VERSION@ # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -61,7 +61,7 @@ PROJECT_BRIEF = # pixels and the maximum width should not exceed 200 pixels. Doxygen will copy # the logo to the output directory. -PROJECT_LOGO = ../_doxygen/logo.png +PROJECT_LOGO = @NRFBM_BASE@/doc/_doxygen/logo.png # With the PROJECT_ICON tag one can specify an icon that is included in the tabs # when the HTML document is shown. Doxygen will copy the logo to the output @@ -74,7 +74,7 @@ PROJECT_ICON = # entered, it will be relative to the location where Doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = html +OUTPUT_DIRECTORY = @DOCSET_BUILD_DIR@ # If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096 # sub-directories (in 2 levels) under the output directory of each output format @@ -180,7 +180,7 @@ FULL_PATH_NAMES = NO # will be relative from the directory where Doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = ../../components/softdevice/s115/s115_API/ +STRIP_FROM_PATH = @DOCSET_SOURCE_BASE@/components/softdevice/s115/s115_API/ # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -189,7 +189,7 @@ STRIP_FROM_PATH = ../../components/softdevice/s115/s115_API/ # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = ../../components/softdevice/s115/s115_API/include/ +STRIP_FROM_INC_PATH = @DOCSET_SOURCE_BASE@/components/softdevice/s115/s115_API/include/ # If the SHORT_NAMES tag is set to YES, Doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't @@ -955,9 +955,9 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../components/softdevice/s115/s115_API/doc/ \ - ../../components/softdevice/s115/s115_API/include/ \ - s115_mainpage.dox +INPUT = @DOCSET_SOURCE_BASE@/components/softdevice/s115/s115_API/doc/ \ + @DOCSET_SOURCE_BASE@/components/softdevice/s115/s115_API/include/ \ + @DOCSET_SOURCE_BASE@/doc/s115/mainpage.dox # This tag can be used to specify the character encoding of the source files # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses @@ -1284,7 +1284,7 @@ HTML_FILE_EXTENSION = .html # of the possible markers and block names see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_HEADER = ../_doxygen/header.html +HTML_HEADER = @NRFBM_BASE@/doc/_doxygen/header.html # The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each # generated HTML page. If the tag is left blank Doxygen will generate a standard @@ -1324,7 +1324,7 @@ HTML_STYLESHEET = # documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = ../_doxygen/doxygen-awesome.css +HTML_EXTRA_STYLESHEET = @NRFBM_BASE@/doc/_doxygen/doxygen-awesome.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note @@ -1334,9 +1334,9 @@ HTML_EXTRA_STYLESHEET = ../_doxygen/doxygen-awesome.css # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_FILES = ../_doxygen/doxygen-awesome-darkmode-toggle.js \ - ../_doxygen/doxygen-awesome-paragraph-link.js \ - ../_doxygen/doxygen-awesome-interactive-toc.js +HTML_EXTRA_FILES = @NRFBM_BASE@/doc/_doxygen/doxygen-awesome-darkmode-toggle.js \ + @NRFBM_BASE@/doc/_doxygen/doxygen-awesome-paragraph-link.js \ + @NRFBM_BASE@/doc/_doxygen/doxygen-awesome-interactive-toc.js # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output # should be rendered with a dark or light theme.