Skip to content

Commit e8ceb10

Browse files
gmarullb-gent
gmarull
authored and
b-gent
committed
doc: refactor doc generation
So that process is similar to NCS. Signed-off-by: Gerard Marull-Paretas <[email protected]>
1 parent 57ac2de commit e8ceb10

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+685
-309
lines changed

‎doc/CMakeLists.txt‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
# Copyright (c) 2025 Nordic Semiconductor ASA
2+
# SPDX-License-Identifier: LicenseRef-Nordic-5-Clause
3+
4+
# Builds combined documentation for all documentation sets: nRF (including
5+
# Doxygen documentation), S115, etc.
6+
#
7+
# We use our own Sphinx configuration files when building the documentation set
8+
# for each repository, instead of reusing configuration files. See e.g.
9+
# doc/nrfbm/conf.py.
10+
11+
cmake_minimum_required(VERSION 3.20.0)
12+
project(nrf-sdk-bm-doc LANGUAGES NONE)
13+
14+
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE} COMPONENTS doc)
15+
16+
#-------------------------------------------------------------------------------
17+
# Options
18+
19+
set(SPHINXOPTS "-j auto -W --keep-going -T" CACHE STRING "Default Sphinx Options")
20+
set(SPHINXOPTS_EXTRA "" CACHE STRING "Extra Sphinx Options")
21+
22+
separate_arguments(SPHINXOPTS)
23+
separate_arguments(SPHINXOPTS_EXTRA)
24+
25+
#-------------------------------------------------------------------------------
26+
# Dependencies
27+
28+
find_package(Python 3.10)
29+
set(DOXYGEN_SKIP_DOT True)
30+
find_package(Doxygen 1.12.0 REQUIRED)
31+
32+
find_program(SPHINXBUILD sphinx-build)
33+
if(NOT SPHINXBUILD)
34+
message(FATAL_ERROR "The 'sphinx-build' command was not found")
35+
endif()
36+
37+
find_program(SPHINXAUTOBUILD sphinx-autobuild)
38+
if(NOT SPHINXAUTOBUILD)
39+
message(WARNING "sphinx-autobuild not found, HTML hot reloading will not be available.")
40+
endif()
41+
42+
set(KCONFIG_BINARY_DIR ${CMAKE_BINARY_DIR}/kconfig)
43+
list(INSERT MODULE_EXT_ROOT 0 ${ZEPHYR_BASE})
44+
file(MAKE_DIRECTORY ${KCONFIG_BINARY_DIR})
45+
46+
#-------------------------------------------------------------------------------
47+
# Functions
48+
49+
# Add a new Doxygen docset.
50+
#
51+
# Args:
52+
# - name: Docset name.
53+
# - sources: Sources.
54+
# - version: Docset version.
55+
# - STANDALONE: Use if docset is Doxygen-only, i.e., without Sphinx.
56+
#
57+
# Configured targets (if STANDALONE):
58+
# - ${name}: Run Doxygen build.
59+
# - ${name}-clean: Clean build artifacts.
60+
#
61+
# Configured targets (if NOT STANDALONE):
62+
# - ${name}-doxygen: Run Doxygen build.
63+
# - ${name}-doxygen-clean: Clean build artifacts.
64+
#
65+
function(add_doxygen_docset name sources version)
66+
cmake_parse_arguments(DOXYGEN "STANDALONE" "" "" ${ARGN})
67+
set(DOCSET_BUILD_DIR ${CMAKE_BINARY_DIR}/html/${name})
68+
set(DOCSET_SOURCE_BASE ${sources})
69+
set(DOCSET_VERSION ${version})
70+
71+
if(NOT DOXYGEN_STANDALONE)
72+
set(SUFFIX "-doxygen")
73+
set(DOCSET_BUILD_DIR ${DOCSET_BUILD_DIR}/doxygen)
74+
endif()
75+
76+
configure_file(${CMAKE_CURRENT_LIST_DIR}/${name}/${name}.doxyfile.in ${CMAKE_BINARY_DIR}/${name}.doxyfile)
77+
78+
add_custom_target(
79+
${name}${SUFFIX}
80+
COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_BUILD_DIR}
81+
COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_BINARY_DIR}/${name}.doxyfile
82+
USES_TERMINAL
83+
COMMENT "Building ${name} Doxygen docset..."
84+
)
85+
86+
add_custom_target(
87+
${name}${SUFFIX}-clean
88+
COMMAND ${CMAKE_COMMAND} -E rm -rf ${DOCSET_BUILD_DIR}
89+
)
90+
endfunction()
91+
92+
# Add a new docset.
93+
#
94+
# Args:
95+
# - name: Docset name.
96+
# - version: Docset version.
97+
# - DODGY: Enable/disable "dodgy" mode. If enabled "-W" (warnings as errors)
98+
# option will be disabled. It can be useful for external docsets that are
99+
# likely to generate build warnings.
100+
# - SPHINXOPTS: Docset specific Sphinx options
101+
#
102+
# This function configures multiple targets which can be used to build a docset.
103+
# The docset configuration (conf.py) is expected to be at the ${name} folder
104+
# (relative to the current directory). The sources are taken from the
105+
# ${name}/src folder (relative to the build directory). This means that docsets
106+
# need to make use of the external_content extension in order to gather all
107+
# docset sources into that folder.
108+
#
109+
# Configured targets:
110+
# - ${name}: Run Sphinx "html" build.
111+
# - ${name}-live: Run Sphinx "html" live build (if sphinx-autobuild is
112+
# available).
113+
# - ${name}-linkcheck: Run Sphinx "linkcheck" target.
114+
# - ${name}-clean: Clean build artifacts.
115+
#
116+
function(add_docset name version)
117+
cmake_parse_arguments(DOCSET "DODGY" "" "SPHINXOPTS" ${ARGN})
118+
119+
set(DOCSET_CFG_DIR ${CMAKE_CURRENT_LIST_DIR}/${name})
120+
set(DOCSET_BUILD_DIR ${CMAKE_BINARY_DIR}/${name})
121+
set(DOCSET_SRC_DIR ${CMAKE_BINARY_DIR}/${name}/src)
122+
set(DOCSET_DOCTREE_DIR ${CMAKE_BINARY_DIR}/${name}/doctree)
123+
set(DOCSET_HTML_DIR ${CMAKE_BINARY_DIR}/html/${name})
124+
set(DOCSET_LINKCHECK_DIR ${CMAKE_BINARY_DIR}/linkcheck/${name})
125+
set(DOCSET_MAKE_DIRS ${DOCSET_BUILD_DIR};${DOCSET_SRC_DIR};${DOCSET_HTML_DIR})
126+
set(DOCSET_CLEAN_DIRS ${DOCSET_BUILD_DIR};${DOCSET_HTML_DIR})
127+
set(DOCSET_ENV DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE};DOCSET_VERSION=${version};DOCS_HTML_DIR=${DOCSET_HTML_DIR})
128+
129+
if(${DOCSET_DODGY})
130+
list(REMOVE_ITEM SPHINXOPTS "-W" "--keep-going")
131+
endif()
132+
133+
add_doc_target(
134+
${name}
135+
COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_MAKE_DIRS}
136+
COMMAND ${CMAKE_COMMAND} -E env ${DOCSET_ENV}
137+
${SPHINXBUILD}
138+
-b html
139+
-c ${DOCSET_CFG_DIR}
140+
-d ${DOCSET_DOCTREE_DIR}
141+
-w ${DOCSET_BUILD_DIR}/html.log
142+
${SPHINXOPTS}
143+
${SPHINXOPTS_EXTRA}
144+
${DOCSET_SPHINXOPTS}
145+
${EXTRA_ARGS}
146+
${DOCSET_SRC_DIR}
147+
${DOCSET_HTML_DIR}
148+
USES_TERMINAL
149+
COMMENT "Building ${name} docset..."
150+
)
151+
152+
if(SPHINXAUTOBUILD)
153+
add_doc_target(
154+
${name}-live
155+
COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_MAKE_DIRS}
156+
COMMAND ${CMAKE_COMMAND} -E env ${DOCSET_ENV}
157+
${SPHINXAUTOBUILD}
158+
--watch ${DOCSET_CFG_DIR}
159+
--ignore ${DOCSET_BUILD_DIR}
160+
-b html
161+
-c ${DOCSET_CFG_DIR}
162+
-d ${DOCSET_DOCTREE_DIR}
163+
-w ${DOCSET_BUILD_DIR}/html-live.log
164+
${SPHINXOPTS}
165+
${SPHINXOPTS_EXTRA}
166+
${DOCSET_SPHINXOPTS}
167+
${EXTRA_ARGS}
168+
${DOCSET_SRC_DIR}
169+
${DOCSET_HTML_DIR}
170+
USES_TERMINAL
171+
COMMENT "Building ${name}-live docset..."
172+
)
173+
endif()
174+
175+
add_custom_target(
176+
${name}-linkcheck
177+
COMMAND ${CMAKE_COMMAND} -E make_directory ${DOCSET_MAKE_DIRS}
178+
COMMAND ${CMAKE_COMMAND} -E env ${DOCSET_ENV}
179+
${SPHINXBUILD}
180+
-b linkcheck
181+
-c ${DOCSET_CFG_DIR}
182+
-d ${DOCSET_DOCTREE_DIR}
183+
-w ${DOCSET_BUILD_DIR}/linkcheck.log
184+
${SPHINXOPTS}
185+
${SPHINXOPTS_EXTRA}
186+
${DOCSET_SPHINXOPTS}
187+
${EXTRA_ARGS}
188+
${DOCSET_SRC_DIR}
189+
${DOCSET_LINKCHECK_DIR}
190+
USES_TERMINAL
191+
COMMENT "Checking links for ${name} docset..."
192+
)
193+
194+
set_target_properties(
195+
${name} ${name}-all
196+
${name}-linkcheck
197+
PROPERTIES
198+
ADDITIONAL_CLEAN_FILES "${DOCSET_CLEAN_DIRS}"
199+
)
200+
201+
if(SPHINXAUTOBUILD)
202+
set_target_properties(
203+
${name}-live ${name}-live-all
204+
PROPERTIES
205+
ADDITIONAL_CLEAN_FILES "${DOCSET_CLEAN_DIRS}"
206+
)
207+
endif()
208+
209+
add_custom_target(
210+
${name}-clean
211+
COMMAND ${CMAKE_COMMAND} -E rm -rf ${DOCSET_CLEAN_DIRS}
212+
)
213+
endfunction()
214+
215+
# Create a custom doc target.
216+
#
217+
# This function has the same signature as `add_custom_target()`
218+
#
219+
# The function will create two targets for the doc build system.
220+
# - Target 1 named: `<name>`
221+
# - Target 2 named: `<name>-all`
222+
#
223+
# Both targets will produce same result, but target 1 is useful when only
224+
# wanting to build a subset of the docs and missing references to other targets
225+
# are acceptable (warnings will be generated).
226+
#
227+
# Target 2 is used for complete docset builds where it is important that build
228+
# order of each target is under full control.
229+
#
230+
function(add_doc_target name)
231+
add_custom_target(${name} ${ARGN})
232+
add_custom_target(${name}-all ${ARGN})
233+
endfunction()
234+
235+
#-------------------------------------------------------------------------------
236+
# Paths
237+
238+
get_filename_component(NRFBM_BASE ${CMAKE_CURRENT_LIST_DIR}../ DIRECTORY)
239+
get_filename_component(NRF_BASE ${CMAKE_CURRENT_LIST_DIR}../../nrf DIRECTORY)
240+
241+
# HTML output directory
242+
set(HTML_DIR ${CMAKE_BINARY_DIR}/html)
243+
file(MAKE_DIRECTORY ${HTML_DIR})
244+
245+
#-------------------------------------------------------------------------------
246+
# docset: nrfbm
247+
248+
file(READ "${NRFBM_BASE}/VERSION" NRFBM_VERSION)
249+
string(STRIP ${NRFBM_VERSION} NRFBM_VERSION)
250+
251+
add_docset(nrfbm ${NRFBM_VERSION})
252+
add_doxygen_docset(nrfbm ${NRFBM_BASE} ${NRFBM_VERSION})
253+
254+
#-------------------------------------------------------------------------------
255+
# docset: s115
256+
257+
add_doxygen_docset(s115 ${NRFBM_BASE} "9.0.0-3.prototype" STANDALONE)
258+
259+
#-------------------------------------------------------------------------------
260+
# docset: kconfig
261+
262+
add_docset(kconfig "")
263+
264+
#-------------------------------------------------------------------------------
265+
# Global targets
266+
267+
add_custom_target(
268+
copy-extra-content
269+
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_LIST_DIR}/_static/html/index.html ${HTML_DIR}
270+
)
271+
272+
add_custom_target(
273+
merge-search-indexes
274+
COMMAND
275+
${PYTHON_EXECUTABLE}
276+
${NRF_BASE}/doc/_scripts/merge_search_indexes.py
277+
-b ${CMAKE_BINARY_DIR}
278+
COMMENT "Merging search indexes..."
279+
)
280+
281+
add_dependencies(merge-search-indexes
282+
nrfbm-all
283+
kconfig-all
284+
)
285+
286+
# Add dependencies to both a docset-all and docset-live-all targets if available
287+
function(add_doc_dependencies docset)
288+
add_dependencies(${docset}-all ${ARGN})
289+
if(SPHINXAUTOBUILD)
290+
add_dependencies(${docset}-live-all ${ARGN})
291+
endif()
292+
endfunction()
293+
294+
add_doc_dependencies(nrfbm kconfig-all s115)
295+
296+
add_custom_target(build-all ALL)
297+
add_dependencies(build-all
298+
copy-extra-content
299+
merge-search-indexes
300+
nrfbm-all
301+
kconfig-all
302+
s115
303+
)
304+
305+
add_custom_target(linkcheck)
306+
add_dependencies(linkcheck
307+
nrfbm-linkcheck
308+
kconfig-linkcheck
309+
)

‎doc/_static/html/index.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<head>
33

44
<script type="text/javascript">
5-
window.location="html/index.html";
5+
window.location="nrfbm/index.html";
66
</script>
77

88
</head>

‎doc/_utils/redirects.py‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
"""
2+
Copyright (c) 2025 Nordic Semiconductor
3+
SPDX-License-Identifier: Apache-2.0
4+
5+
This module contains per-docset variables with a list of tuples
6+
(old_url, newest_url) for pages that need a redirect. This list allows redirecting
7+
old URLs (caused by, for example, reorganizing doc directories).
8+
9+
Notes:
10+
- Keep URLs relative to document root (NO leading slash and
11+
without the html extension).
12+
- Keep URLs in the order of pages from the doc hierarchy. Move entry order if hierarchy changes.
13+
- Comments mention the page name; edit the comment when the page name changes.
14+
- Each comment is valid for the line where it is added AND all lines without comment after it.
15+
- If a page was removed, mention in the comment when it was removed, if possible.
16+
A redirect should still point to another page.
17+
18+
Examples:
19+
("old/README", "absolutely/newer/index"), # Name of the page
20+
("new/index", "absolutely/newer/index"),
21+
("even/newer/index", "absolutely/newer/index"),
22+
"""
23+
24+
NRFBM = [
25+
]

0 commit comments

Comments
 (0)