From 316ecabb4e700415a435b920bec0ff5da16a4e8c Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Fri, 24 Oct 2025 15:26:18 +0200 Subject: [PATCH 1/2] doc: nrfbm: doxyfile: disable all warnings until errors are fixed This is a temporary solution, but all errors should be fixed and this patch reverted. Warning given! Signed-off-by: Gerard Marull-Paretas --- doc/nrf-bm/doxygen/nrf-bm.doxyfile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/nrf-bm/doxygen/nrf-bm.doxyfile b/doc/nrf-bm/doxygen/nrf-bm.doxyfile index 61c5aa6471..43640079bd 100644 --- a/doc/nrf-bm/doxygen/nrf-bm.doxyfile +++ b/doc/nrf-bm/doxygen/nrf-bm.doxyfile @@ -857,14 +857,14 @@ QUIET = YES # Tip: Turn warnings on while writing the documentation. # The default value is: YES. -WARNINGS = YES +WARNINGS = NO # If the WARN_IF_UNDOCUMENTED tag is set to YES then Doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If the WARN_IF_DOC_ERROR tag is set to YES, Doxygen will generate warnings for # potential errors in the documentation, such as documenting some parameters in @@ -872,14 +872,14 @@ WARN_IF_UNDOCUMENTED = YES # using markup commands wrongly. # The default value is: YES. -WARN_IF_DOC_ERROR = YES +WARN_IF_DOC_ERROR = NO # If WARN_IF_INCOMPLETE_DOC is set to YES, Doxygen will warn about incomplete # function parameter documentation. If set to NO, Doxygen will accept that some # parameters have no documentation without warning. # The default value is: YES. -WARN_IF_INCOMPLETE_DOC = YES +WARN_IF_INCOMPLETE_DOC = NO # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return From c43b7f739580b3850d31c741d2bac508ce2662bb Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Thu, 25 Sep 2025 14:32:01 +0200 Subject: [PATCH 2/2] doc: refactor doc generation So that process is similar to NCS. Signed-off-by: Gerard Marull-Paretas --- .github/workflows/docs.yml | 60 +++- doc/CMakeLists.txt | 308 ++++++++++++++++++ doc/_doxygen/aliases.doxyfile | 9 +- doc/_scripts/merge_search_indexes.py | 215 ++++++++++++ doc/_static/html/index.html | 2 +- doc/_utils/redirects.py | 25 ++ doc/_utils/utils.py | 104 ++++++ doc/kconfig/conf.py | 76 +++++ doc/kconfig/index.rst | 24 ++ doc/kconfig/regex.rst | 14 + doc/nrf-bm/conf.py | 67 ---- doc/nrf-bm/gen_docs.py | 154 --------- doc/nrf-bm/requirements.txt | 5 - doc/{nrf-bm => nrfbm}/README.md | 0 doc/{nrf-bm => nrfbm}/api/api.rst | 62 +--- .../app_dev/dfu/bootloader_keys.rst | 0 doc/{nrf-bm => nrfbm}/app_dev/dfu/index.rst | 0 .../app_dev/dfu/memory_partitioning.rst | 0 .../app_dev/dfu/single_bank_dfu.rst | 0 doc/{nrf-bm => nrfbm}/app_dev/dfu/ug_dfu.rst | 0 doc/nrfbm/conf.py | 101 ++++++ doc/{nrf-bm => nrfbm}/doxygen/mainpage.dox | 0 doc/{nrf-bm => nrfbm}/drivers.rst | 0 doc/{nrf-bm => nrfbm}/drivers/lpuarte.rst | 0 .../images/add_build_configuration.png | Bin .../images/add_build_configuration_page.png | Bin doc/{nrf-bm => nrfbm}/images/board_target.png | Bin ...pplication_from_sample_quick_pick_menu.png | Bin .../images/dfu_softdevice.svg | 0 .../images/dfu_steps_sd_fwl.svg | 0 .../images/erase_and_flash_to_board.png | Bin .../images/image_header_tlv.svg | 0 .../images/nrf5_bm_memory_part.svg | 0 .../images/partition_RRAM.svg | 0 .../images/show_build_configuration_files.png | Bin ...show_build_configuration_files_mcuboot.png | Bin .../images/single_bank_dfu_steps.svg | 0 .../includes/configure_and_build_sample.txt | 0 .../includes/create_sample.txt | 0 .../includes/program_sample.txt | 0 .../includes/softdevice_flash.txt | 0 doc/{nrf-bm => nrfbm}/index.rst | 0 doc/{nrf-bm => nrfbm}/install_nrf_bm.rst | 0 .../libraries/bluetooth/ble_adv.rst | 0 .../libraries/bluetooth/ble_conn_params.rst | 0 .../libraries/bluetooth/ble_gatt_queue.rst | 0 .../libraries/bluetooth/ble_qwr.rst | 0 .../bluetooth/ble_radio_notification.rst | 0 .../libraries/bluetooth/index.rst | 0 .../libraries/bluetooth/peer_manager.rst} | 0 .../libraries/bluetooth/services/ble_bas.rst | 0 .../libraries/bluetooth/services/ble_cgms.rst | 0 .../libraries/bluetooth/services/ble_dis.rst | 0 .../libraries/bluetooth/services/ble_hids.rst | 0 .../libraries/bluetooth/services/ble_hrs.rst | 0 .../libraries/bluetooth/services/ble_lbs.rst | 0 .../bluetooth/services/ble_mcumgr.rst | 0 .../libraries/bluetooth/services/ble_nus.rst | 0 .../libraries/bm_storage.rst | 0 doc/{nrf-bm => nrfbm}/libraries/bm_zms.rst | 0 doc/{nrf-bm => nrfbm}/libraries/buttons.rst | 0 .../libraries/event_scheduler.rst | 0 doc/{nrf-bm => nrfbm}/libraries/index.rst | 0 doc/{nrf-bm => nrfbm}/libraries/nrf_sdh.rst | 0 doc/{nrf-bm => nrfbm}/libraries/sensorsim.rst | 0 doc/{nrf-bm => nrfbm}/libraries/timer.rst | 0 doc/{nrf-bm => nrfbm}/links.txt | 0 .../migration/nrf5_bm_migration.rst | 0 .../nrfbm.doxyfile.in} | 62 ++-- doc/{nrf-bm => nrfbm}/release_notes.rst | 0 .../release_notes/release_notes_0.1.0.rst | 0 .../release_notes/release_notes_0.7.0.rst | 0 .../release_notes/release_notes_0.8.0.rst | 2 +- .../release_notes/release_notes_0.9.0.rst | 0 .../release_notes/release_notes_changelog.rst | 0 doc/{nrf-bm => nrfbm}/s115_docs.rst | 0 doc/{nrf-bm => nrfbm}/sample/ble.rst | 0 doc/{nrf-bm => nrfbm}/sample/dfu.rst | 0 doc/{nrf-bm => nrfbm}/sample/peripheral.rst | 0 doc/{nrf-bm => nrfbm}/sample/subsys.rst | 0 doc/{nrf-bm => nrfbm}/samples.rst | 0 doc/{nrf-bm => nrfbm}/shortcuts.txt | 0 doc/{nrf-bm => nrfbm}/substitutions.txt | 0 doc/requirements.txt | 8 + doc/s115/{s115_mainpage.dox => mainpage.dox} | 0 doc/s115/{s115.doxyfile => s115.doxyfile.in} | 34 +- 86 files changed, 978 insertions(+), 354 deletions(-) create mode 100644 doc/CMakeLists.txt create mode 100644 doc/_scripts/merge_search_indexes.py create mode 100644 doc/_utils/redirects.py create mode 100644 doc/_utils/utils.py create mode 100644 doc/kconfig/conf.py create mode 100644 doc/kconfig/index.rst create mode 100644 doc/kconfig/regex.rst delete mode 100644 doc/nrf-bm/conf.py delete mode 100644 doc/nrf-bm/gen_docs.py delete mode 100644 doc/nrf-bm/requirements.txt rename doc/{nrf-bm => nrfbm}/README.md (100%) rename doc/{nrf-bm => nrfbm}/api/api.rst (81%) rename doc/{nrf-bm => nrfbm}/app_dev/dfu/bootloader_keys.rst (100%) rename doc/{nrf-bm => nrfbm}/app_dev/dfu/index.rst (100%) rename doc/{nrf-bm => nrfbm}/app_dev/dfu/memory_partitioning.rst (100%) rename doc/{nrf-bm => nrfbm}/app_dev/dfu/single_bank_dfu.rst (100%) rename doc/{nrf-bm => nrfbm}/app_dev/dfu/ug_dfu.rst (100%) create mode 100644 doc/nrfbm/conf.py rename doc/{nrf-bm => nrfbm}/doxygen/mainpage.dox (100%) rename doc/{nrf-bm => nrfbm}/drivers.rst (100%) rename doc/{nrf-bm => nrfbm}/drivers/lpuarte.rst (100%) rename doc/{nrf-bm => nrfbm}/images/add_build_configuration.png (100%) rename doc/{nrf-bm => nrfbm}/images/add_build_configuration_page.png (100%) rename doc/{nrf-bm => nrfbm}/images/board_target.png (100%) rename doc/{nrf-bm => nrfbm}/images/create_new_application_from_sample_quick_pick_menu.png (100%) rename doc/{nrf-bm => nrfbm}/images/dfu_softdevice.svg (100%) rename doc/{nrf-bm => nrfbm}/images/dfu_steps_sd_fwl.svg (100%) rename doc/{nrf-bm => nrfbm}/images/erase_and_flash_to_board.png (100%) rename doc/{nrf-bm => nrfbm}/images/image_header_tlv.svg (100%) rename doc/{nrf-bm => nrfbm}/images/nrf5_bm_memory_part.svg (100%) rename doc/{nrf-bm => nrfbm}/images/partition_RRAM.svg (100%) rename doc/{nrf-bm => nrfbm}/images/show_build_configuration_files.png (100%) rename doc/{nrf-bm => nrfbm}/images/show_build_configuration_files_mcuboot.png (100%) rename doc/{nrf-bm => nrfbm}/images/single_bank_dfu_steps.svg (100%) rename doc/{nrf-bm => nrfbm}/includes/configure_and_build_sample.txt (100%) rename doc/{nrf-bm => nrfbm}/includes/create_sample.txt (100%) rename doc/{nrf-bm => nrfbm}/includes/program_sample.txt (100%) rename doc/{nrf-bm => nrfbm}/includes/softdevice_flash.txt (100%) rename doc/{nrf-bm => nrfbm}/index.rst (100%) rename doc/{nrf-bm => nrfbm}/install_nrf_bm.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/ble_adv.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/ble_conn_params.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/ble_gatt_queue.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/ble_qwr.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/ble_radio_notification.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/index.rst (100%) rename doc/{nrf-bm/libraries/bluetooth/ble_peer_manager.rst => nrfbm/libraries/bluetooth/peer_manager.rst} (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_bas.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_cgms.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_dis.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_hids.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_hrs.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_lbs.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_mcumgr.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bluetooth/services/ble_nus.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bm_storage.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/bm_zms.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/buttons.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/event_scheduler.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/index.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/nrf_sdh.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/sensorsim.rst (100%) rename doc/{nrf-bm => nrfbm}/libraries/timer.rst (100%) rename doc/{nrf-bm => nrfbm}/links.txt (100%) rename doc/{nrf-bm => nrfbm}/migration/nrf5_bm_migration.rst (100%) rename doc/{nrf-bm/doxygen/nrf-bm.doxyfile => nrfbm/nrfbm.doxyfile.in} (98%) rename doc/{nrf-bm => nrfbm}/release_notes.rst (100%) rename doc/{nrf-bm => nrfbm}/release_notes/release_notes_0.1.0.rst (100%) rename doc/{nrf-bm => nrfbm}/release_notes/release_notes_0.7.0.rst (100%) rename doc/{nrf-bm => nrfbm}/release_notes/release_notes_0.8.0.rst (99%) rename doc/{nrf-bm => nrfbm}/release_notes/release_notes_0.9.0.rst (100%) rename doc/{nrf-bm => nrfbm}/release_notes/release_notes_changelog.rst (100%) rename doc/{nrf-bm => nrfbm}/s115_docs.rst (100%) rename doc/{nrf-bm => nrfbm}/sample/ble.rst (100%) rename doc/{nrf-bm => nrfbm}/sample/dfu.rst (100%) rename doc/{nrf-bm => nrfbm}/sample/peripheral.rst (100%) rename doc/{nrf-bm => nrfbm}/sample/subsys.rst (100%) rename doc/{nrf-bm => nrfbm}/samples.rst (100%) rename doc/{nrf-bm => nrfbm}/shortcuts.txt (100%) rename doc/{nrf-bm => nrfbm}/substitutions.txt (100%) create mode 100644 doc/requirements.txt rename doc/s115/{s115_mainpage.dox => mainpage.dox} (100%) rename doc/s115/{s115.doxyfile => s115.doxyfile.in} (99%) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b87d1d374b..fda5252424 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,6 +1,9 @@ name: Documentation Build -on: [push, pull_request, workflow_dispatch] +on: [push, pull_request] + +env: + DOXYGEN_VERSION: 1.12.0 jobs: build: @@ -8,14 +11,43 @@ jobs: steps: - name: Checkout uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4 + with: + ref: ${{ github.event.pull_request.head.sha }} + fetch-depth: 0 + path: sdk-nrf-bm/nrf-bm - - name: Install Doxygen - run: sudo apt-get install -y doxygen + - name: Install system dependencies + run: | + sudo apt-get install -y cmake ninja-build + wget --no-verbose "https://github.com/doxygen/doxygen/releases/download/Release_${DOXYGEN_VERSION//./_}/doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz" + sudo tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz -C /opt + echo "/opt/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH + + - name: Set up Python + uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c # v6.0.0 + with: + python-version: 3.12 + cache: pip + cache-dependency-path: sdk-nrf-bm/nrf-bm/doc/requirements.txt + + - name: Install Python dependencies + working-directory: sdk-nrf-bm/nrf-bm + run: | + pip install west + pip install -r doc/requirements.txt + + - name: West update + working-directory: sdk-nrf-bm/nrf-bm + run: | + west init -l . + west update -o=--depth=1 -n + west zephyr-export - name: Build + working-directory: sdk-nrf-bm/nrf-bm run: | - cd doc/nrf-bm - python3 gen_docs.py + cmake -G Ninja -S doc -B doc/_build + cmake --build doc/_build - name: Check version run: | @@ -31,7 +63,7 @@ jobs: echo "VERSION=${VERSION}" >> "$GITHUB_ENV" - name: Prepare Azure upload - working-directory: doc/nrf-bm/_build/html + working-directory: sdk-nrf-bm/nrf-bm/doc/_build/html run: | MONITOR="monitor_${{ github.run_id }}.txt" @@ -48,7 +80,7 @@ jobs: zip -rq "${ARCHIVE}" . - name: Find nRF Connect SDK Bare Metal Edited Documents - working-directory: doc + working-directory: sdk-nrf-bm/nrf-bm run: | COMMENT="comment.txt" PREFIX="https://ncsbmdoc.z6.web.core.windows.net/PR-${{ github.event.pull_request.number }}/" @@ -56,13 +88,13 @@ jobs: echo "You can find the documentation preview for this PR [here](${PREFIX})." >> $COMMENT - name: Stage files for publish + working-directory: sdk-nrf-bm/nrf-bm run: | - rm -rf publish - mkdir -p publish - cp doc/nrf-bm/_build/html/monitor_*.txt publish/ - cp doc/nrf-bm/_build/html/*.zip publish/ - if [[ -f doc/nrf-bm/_build/html/pr.txt ]]; then cp doc/nrf-bm/_build/html/pr.txt publish/; fi - cp doc/comment.txt publish/ + mkdir publish + cp doc/_build/html/monitor_*.txt publish/ + cp doc/_build/html/*.zip publish/ + if [[ -f doc/_build/html/pr.txt ]]; then cp doc/_build/html/pr.txt publish/; fi + cp comment.txt publish/ - name: Store if: ${{ !contains(github.event.pull_request.labels.*.name, 'external') || contains(github.event.pull_request.labels.*.name, 'CI-trusted-author') }} @@ -71,4 +103,4 @@ jobs: name: docs retention-days: 5 path: | - publish/* + sdk-nrf-bm/nrf-bm/publish/* diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt new file mode 100644 index 0000000000..5a18255b1b --- /dev/null +++ b/doc/CMakeLists.txt @@ -0,0 +1,308 @@ +# 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 + +set(NRFBM_BASE ${CMAKE_CURRENT_LIST_DIR}/..) + +# 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} + ${NRFBM_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/_doxygen/aliases.doxyfile b/doc/_doxygen/aliases.doxyfile index e5e52def16..b482e7191d 100644 --- a/doc/_doxygen/aliases.doxyfile +++ b/doc/_doxygen/aliases.doxyfile @@ -1,12 +1,11 @@ ALIASES += \ ### Aliases from SD -ALIASES += events="
Events generated
" +ALIASES += events="
Events generated
" ALIASES += event{1}="" -ALIASES += event{2}="" +ALIASES += event{2}="" ALIASES += endevents="
\1
\1\2
\1\2
" -# @msc is reserved, use @mmsc as "my @msc" -ALIASES += mscs="
Relevant Message Sequence Charts
" -ALIASES += mmsc{1}="" +ALIASES += mscs="
Relevant Message Sequence Charts
\1
" +ALIASES += mmsc{1}="" ALIASES += endmscs="
\1
" diff --git a/doc/_scripts/merge_search_indexes.py b/doc/_scripts/merge_search_indexes.py new file mode 100644 index 0000000000..0eaa6b732d --- /dev/null +++ b/doc/_scripts/merge_search_indexes.py @@ -0,0 +1,215 @@ +""" +Sphinx search index merge utility +================================= + +This script can be used to merge search indexes of multiple docsets, thus +allowing to obtain a cross-search experience. + +Credits go to Dominik Kilian for the original idea and part of this code. + +Usage +***** + +python merge_search_indexes.py -b path/to/doc/build/dir + +Copyright (c) 2021 Nordic Semiconductor ASA +""" + +import argparse +import copy +import json +from pathlib import Path +import re +import shutil +import sys +from typing import Dict + + +sys.path.insert(0, str(Path(__file__).absolute().parents[1] / "_utils")) +import utils + + +def load_search_index(file: Path, prefix: str) -> Dict: + """Load search index from a file + + Args: + file: Index file. + prefix: Index prefix name. + + Returns: + Search index. + """ + + with open(file) as f: + m = re.match(r"^Search\.setIndex\((.*)\)$", f.read()) + if not m: + raise ValueError(f"Unexpected search index content for {file}") + + escaped = re.sub(r"([{,])([A-Za-z0-9_]+):", r'\1"\2":', m.group(1)) + + index = json.loads(escaped) + index["titles"] = [f"{prefix} ยป {title}" for title in index["titles"]] + + return index + + +def dump_search_index(index: Dict, dst: Path) -> None: + """Dump a search index to a file. + + Args: + index: Search index. + dst: Destination file. + """ + + with open(dst, "w") as f: + f.write("Search.setIndex(") + f.write(json.dumps(index)) + f.write(");") + + +def merge_doc_file_names(src: Dict, dst: Dict, src_docset: str) -> None: + """Merge docnames and filenames entries. + + Args: + src: Source index. + dst: Destination index. + src_docset: Source index docset name. + """ + + for docname in src["docnames"]: + dst["docnames"].append(f"../{src_docset}/{docname}") + for filename in src["filenames"]: + dst["filenames"].append(f"../{src_docset}/{filename}") + + dst["titles"] += src["titles"] + + +def merge_terms(src: Dict, dst: Dict, offset: int) -> None: + """Merge terms entries. + + This function merges the terms or titleterms fields of a source index into + a destination index. Entries from source index are padded with the provided + offset so that they point to the correct document index. + + Args: + src: Source index. + dst: Destination index. + offset: Offset to be applied to the source index entries. + """ + + for key in ("terms", "titleterms"): + src_entry = src[key] + dst_entry = dst[key] + + for term, values in src_entry.items(): + try: + existing = dst_entry[term] + except KeyError: + existing = list() + + if not isinstance(existing, list): + existing = [existing] + + if not isinstance(values, list): + values = [values] + + dst_entry[term] = existing + [value + offset for value in values] + + +def merge_objects(src: Dict, dst: Dict, offset: int) -> None: + """Merge objects entries + + Args: + src: Source index. + dst: Destination index. + offset: Offset to be applied to the source index entries. + """ + + # merge objnames and objtypes entries + index_cnt = len(dst["objnames"]) - 1 + obj_map = dict() + for src_index, src_value in src["objnames"].items(): + found = False + for dst_index, dst_value in dst["objnames"].items(): + if ( + src_value == dst_value + and src["objtypes"][src_index] == dst["objtypes"][dst_index] + ): + obj_map[src_index] = dst_index + found = True + break + + if not found: + index_cnt += 1 + obj_map[src_index] = index_cnt + dst["objnames"][str(index_cnt)] = src_value + dst["objtypes"][str(index_cnt)] = src["objtypes"][src_index] + + # merge objects + for src_prefix, src_objects in src["objects"].items(): + if src_prefix not in dst["objects"]: + dst["objects"][src_prefix] = list() + + dst_objects = dst["objects"][src_prefix] + for src_object in src_objects: + dst_objects.append([ + src_object[0] + offset, + obj_map[str(src_object[1])], + src_object[2], + src_object[3], + src_object[4], + ]) + + +def main(build_dir: Path) -> None: + """Entry point + + Args: + build_dir: Documentation build directory. + """ + + # discover built docsets + docsets = list() + for entry in (build_dir / "html").iterdir(): + if entry.is_dir() and entry.name in utils.ALL_DOCSETS: + docsets.append(entry.name) + + # load indexes + indexes = dict() + for docset in docsets: + index_file = build_dir / "html" / docset / "searchindex.orig.js" + if not index_file.exists(): + shutil.copy(build_dir / "html" / docset / "searchindex.js", index_file) + + indexes[docset] = load_search_index(index_file, utils.ALL_DOCSETS[docset][0]) + + # merge indexes + for docset, index in indexes.items(): + final_index = copy.deepcopy(index) + for docset_to_merge, index_to_merge in indexes.items(): + if docset_to_merge == docset: + continue + + offset = len(final_index["docnames"]) + + merge_doc_file_names(index_to_merge, final_index, docset_to_merge) + merge_terms(index_to_merge, final_index, offset) + merge_objects(index_to_merge, final_index, offset) + + dump_search_index(final_index, build_dir / "html" / docset / "searchindex.js") + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(allow_abbrev=False) + + parser.add_argument( + "-b", + "--build-dir", + type=Path, + required=True, + help="Documentation build directory", + ) + + args = parser.parse_args() + + main(args.build_dir) 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..813530406c --- /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..e2f326db96 --- /dev/null +++ b/doc/kconfig/conf.py @@ -0,0 +1,76 @@ +# 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" +) +os.environ["ZEPHYR_NRF_KCONFIG"] = str( + NRF_BASE + / "Kconfig.nrf" +) +os.environ["SYSBUILD_NRF_KCONFIG"] = str( + NRF_BASE + / "sysbuild" + / "Kconfig.sysbuild" +) + +# 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 a1bb722ff3..0000000000 --- a/doc/nrf-bm/gen_docs.py +++ /dev/null @@ -1,154 +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") -# Path to the _static directory -static_dir = os.path.abspath("../_static") -# Path to the requirements.txt file -requirements_path = os.path.join(script_dir, "requirements.txt") -# Path to the includes directory -includes_dir = os.path.join(script_dir, "includes") -# Path to the sample directory -sample_dir = os.path.join(script_dir, "sample") -# Path to the PDF source directory -pdf_source_dir = os.path.abspath('../../components/softdevice/s115/') -# Destination directory within _static -pdf_destination_dir = os.path.join(source_dir, 'pdfs') -# Path to the images directory -images_dir = os.path.join(script_dir, "images") -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 fc79992291..79c94f98e2 100644 --- a/doc/nrf-bm/api/api.rst +++ b/doc/nrfbm/api/api.rst @@ -18,8 +18,6 @@ Bluetooth LE Advertising library ================================ .. doxygengroup:: ble_adv - :inner: - :members: .. _api_ble_adv_data_encoder: @@ -27,8 +25,6 @@ Advertising and Scan Response Data Encoder ------------------------------------------ .. doxygengroup:: ble_sdk_lib_advdata - :inner: - :members: .. _api_ble_conn_params: @@ -36,8 +32,6 @@ Bluetooth LE Connection Parameter library ========================================= .. doxygengroup:: ble_conn_params - :inner: - :members: .. _api_ble_conn_state: @@ -45,8 +39,6 @@ Bluetooth LE Connection State library ===================================== .. doxygengroup:: ble_conn_state - :inner: - :members: .. _api_ble_radio_notif: @@ -54,8 +46,6 @@ Bluetooth LE Radio Notification library ======================================= .. doxygengroup:: ble_radio_notification - :inner: - :members: .. _api_bm_buttons: @@ -63,8 +53,6 @@ Bare Metal Buttons library ========================== .. doxygengroup:: bm_buttons - :inner: - :members: .. _api_event_scheduler: @@ -72,8 +60,6 @@ Bare Metal Event Scheduler library ================================== .. doxygengroup:: event_scheduler - :inner: - :members: .. _api_bm_lpuarte: @@ -81,8 +67,6 @@ Bare Metal Low Power UART with EasyDMA driver ============================================= .. doxygengroup:: bm_lpuarte - :inner: - :members: .. _api_storage: @@ -90,15 +74,11 @@ Bare Metal Storage library ========================== .. doxygengroup:: bm_storage - :inner: - :members: Bare Metal Storage library backend ---------------------------------- .. doxygengroup:: bm_storage_backend - :inner: - :members: .. _api_bm_timer: @@ -106,8 +86,6 @@ Bare Metal Timer library ======================== .. doxygengroup:: bm_timer - :inner: - :members: .. _api_ble_bm_zms: @@ -115,17 +93,13 @@ Bare Metal Zephyr Memory Storage (ZMS) ====================================== .. doxygengroup:: bm_zms - :inner: - :members: -.. _api_gatt_queue: +.. _api_ble_gatt_queue: GATT Queue ========== .. doxygengroup:: ble_gq - :inner: - :members: .. _api_peer_manager: @@ -133,8 +107,6 @@ Peer Manager library ==================== .. doxygengroup:: peer_manager - :inner: - :members: .. _api_queued_writes: @@ -142,15 +114,11 @@ Queued Writes module ==================== .. doxygengroup:: ble_qwr - :inner: - :members: Record Access Control Point =========================== .. doxygengroup:: ble_racp - :inner: - :members: .. _api_sensorsim: @@ -158,8 +126,6 @@ Sensor data simulator library ============================= .. doxygengroup:: sensorsim - :inner: - :members: Services ******** @@ -170,8 +136,6 @@ Battery Service =============== .. doxygengroup:: ble_bas - :inner: - :members: .. _api_ble_cgms: @@ -179,8 +143,6 @@ Continuous Glucose Monitoring Service ===================================== .. doxygengroup:: ble_cgms - :inner: - :members: .. _api_dis: @@ -188,8 +150,6 @@ Device Information Service ========================== .. doxygengroup:: ble_dis - :inner: - :members: .. _api_ble_hrs: @@ -197,8 +157,6 @@ Heart Rate Service ================== .. doxygengroup:: ble_hrs - :inner: - :members: .. _api_human_interface_device_service: @@ -206,8 +164,6 @@ Human Interface Device Service ============================== .. doxygengroup:: ble_hids - :inner: - :members: .. _api_lbs: @@ -215,8 +171,6 @@ LED Button Service ================== .. doxygengroup:: ble_lbs - :inner: - :members: .. _api_mcu_manager_service: @@ -224,8 +178,6 @@ MCU manager Service (MCUmgr) ============================ .. doxygengroup:: ble_mcumgr - :inner: - :members: .. _api_ble_nus: @@ -233,15 +185,11 @@ Nordic UART Service (NUS) ========================= .. doxygengroup:: ble_nus - :inner: - :members: SoftDevice Handler ****************** .. doxygengroup:: nrf_sdh - :inner: - :members: Utils ***** @@ -250,26 +198,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..6856d0fc85 --- /dev/null +++ b/doc/nrfbm/conf.py @@ -0,0 +1,101 @@ +# 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"), + (NRFBM_BASE / "components" / "softdevice" / "s115" / "doc", "s115_9.0.0-4.*.main.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/erase_and_flash_to_board.png b/doc/nrfbm/images/erase_and_flash_to_board.png similarity index 100% rename from doc/nrf-bm/images/erase_and_flash_to_board.png rename to doc/nrfbm/images/erase_and_flash_to_board.png 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_adv.rst b/doc/nrfbm/libraries/bluetooth/ble_adv.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/ble_adv.rst rename to doc/nrfbm/libraries/bluetooth/ble_adv.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/ble_gatt_queue.rst b/doc/nrfbm/libraries/bluetooth/ble_gatt_queue.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/ble_gatt_queue.rst rename to doc/nrfbm/libraries/bluetooth/ble_gatt_queue.rst diff --git a/doc/nrf-bm/libraries/bluetooth/ble_qwr.rst b/doc/nrfbm/libraries/bluetooth/ble_qwr.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/ble_qwr.rst rename to doc/nrfbm/libraries/bluetooth/ble_qwr.rst diff --git a/doc/nrf-bm/libraries/bluetooth/ble_radio_notification.rst b/doc/nrfbm/libraries/bluetooth/ble_radio_notification.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/ble_radio_notification.rst rename to doc/nrfbm/libraries/bluetooth/ble_radio_notification.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/ble_peer_manager.rst b/doc/nrfbm/libraries/bluetooth/peer_manager.rst similarity index 100% rename from doc/nrf-bm/libraries/bluetooth/ble_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_storage.rst b/doc/nrfbm/libraries/bm_storage.rst similarity index 100% rename from doc/nrf-bm/libraries/bm_storage.rst rename to doc/nrfbm/libraries/bm_storage.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/buttons.rst b/doc/nrfbm/libraries/buttons.rst similarity index 100% rename from doc/nrf-bm/libraries/buttons.rst rename to doc/nrfbm/libraries/buttons.rst diff --git a/doc/nrf-bm/libraries/event_scheduler.rst b/doc/nrfbm/libraries/event_scheduler.rst similarity index 100% rename from doc/nrf-bm/libraries/event_scheduler.rst rename to doc/nrfbm/libraries/event_scheduler.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/libraries/nrf_sdh.rst b/doc/nrfbm/libraries/nrf_sdh.rst similarity index 100% rename from doc/nrf-bm/libraries/nrf_sdh.rst rename to doc/nrfbm/libraries/nrf_sdh.rst diff --git a/doc/nrf-bm/libraries/sensorsim.rst b/doc/nrfbm/libraries/sensorsim.rst similarity index 100% rename from doc/nrf-bm/libraries/sensorsim.rst rename to doc/nrfbm/libraries/sensorsim.rst diff --git a/doc/nrf-bm/libraries/timer.rst b/doc/nrfbm/libraries/timer.rst similarity index 100% rename from doc/nrf-bm/libraries/timer.rst rename to doc/nrfbm/libraries/timer.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 43640079bd..5c608f0dee 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 @@ -857,14 +863,14 @@ QUIET = YES # Tip: Turn warnings on while writing the documentation. # The default value is: YES. -WARNINGS = NO +WARNINGS = YES # If the WARN_IF_UNDOCUMENTED tag is set to YES then Doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = NO +WARN_IF_UNDOCUMENTED = YES # If the WARN_IF_DOC_ERROR tag is set to YES, Doxygen will generate warnings for # potential errors in the documentation, such as documenting some parameters in @@ -872,14 +878,14 @@ WARN_IF_UNDOCUMENTED = NO # using markup commands wrongly. # The default value is: YES. -WARN_IF_DOC_ERROR = NO +WARN_IF_DOC_ERROR = YES # If WARN_IF_INCOMPLETE_DOC is set to YES, Doxygen will warn about incomplete # function parameter documentation. If set to NO, Doxygen will accept that some # parameters have no documentation without warning. # The default value is: YES. -WARN_IF_INCOMPLETE_DOC = NO +WARN_IF_INCOMPLETE_DOC = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return @@ -955,16 +961,16 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../../../include/ \ - ../../../include/bm/ \ - ../../../include/bm/bluetooth \ - ../../../include/bm/bluetooth/services \ - ../../../include/bm/bluetooth/peer_manager \ - ../../../include/bm/drivers \ - ../../../include/bm/fs \ - ../../../include/bm/softdevice_handler \ - ../../../include/bm/storage \ - mainpage.dox +INPUT = @DOCSET_SOURCE_BASE@/include/ \ + @DOCSET_SOURCE_BASE@/include/bm/ \ + @DOCSET_SOURCE_BASE@/include/bm/bluetooth \ + @DOCSET_SOURCE_BASE@/include/bm/bluetooth/services \ + @DOCSET_SOURCE_BASE@/include/bm/bluetooth/peer_manager \ + @DOCSET_SOURCE_BASE@/include/bm/drivers \ + @DOCSET_SOURCE_BASE@/include/bm/fs \ + @DOCSET_SOURCE_BASE@/include/bm/softdevice_handler \ + @DOCSET_SOURCE_BASE@/include/bm/storage \ + @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 @@ -1291,7 +1297,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 @@ -1331,7 +1337,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 @@ -1341,9 +1347,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. @@ -2230,7 +2237,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 @@ -2401,7 +2408,6 @@ INCLUDE_FILE_PATTERNS = # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. PREDEFINED = __DOXYGEN__ \ - CONFIG_BLE_QWR_MAX_ATTR=1 \ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2835,5 +2841,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 99% 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 index e1e56b2c06..1c12c16e31 100644 --- a/doc/nrf-bm/release_notes/release_notes_0.8.0.rst +++ b/doc/nrfbm/release_notes/release_notes_0.8.0.rst @@ -213,7 +213,7 @@ Peripheral samples * :ref:`bm_zms_sample` sample. * :ref:`bm_lpuarte_sample` sample. - * :ref:`storage_sample` sample. + * :ref:`bm_storage_sample` sample. DFU samples ----------- 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/sample/subsys.rst b/doc/nrfbm/sample/subsys.rst similarity index 100% rename from doc/nrf-bm/sample/subsys.rst rename to doc/nrfbm/sample/subsys.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..5b10873c4d --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,8 @@ +doxmlparser +python-dotenv +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..53a21775f4 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 @@ -857,14 +857,14 @@ QUIET = YES # Tip: Turn warnings on while writing the documentation. # The default value is: YES. -WARNINGS = YES +WARNINGS = NO # If the WARN_IF_UNDOCUMENTED tag is set to YES then Doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If the WARN_IF_DOC_ERROR tag is set to YES, Doxygen will generate warnings for # potential errors in the documentation, such as documenting some parameters in @@ -872,14 +872,14 @@ WARN_IF_UNDOCUMENTED = YES # using markup commands wrongly. # The default value is: YES. -WARN_IF_DOC_ERROR = YES +WARN_IF_DOC_ERROR = NO # If WARN_IF_INCOMPLETE_DOC is set to YES, Doxygen will warn about incomplete # function parameter documentation. If set to NO, Doxygen will accept that some # parameters have no documentation without warning. # The default value is: YES. -WARN_IF_INCOMPLETE_DOC = YES +WARN_IF_INCOMPLETE_DOC = NO # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return @@ -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.