Skip to content

Commit 2bb41b6

Browse files
b-genteivindj-nordic
b-gent
authored and
eivindj-nordic
committed
doc: Add Breathe extension to link Doxygen docs
Add Breathe for API documentation. Signed-off-by: Bartosz Gentkowski <[email protected]>
1 parent 56c375c commit 2bb41b6

File tree

8 files changed

+231
-8
lines changed

8 files changed

+231
-8
lines changed

‎.github/workflows/docs.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ jobs:
99
- name: Checkout
1010
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
1111

12+
- name: Install Doxygen
13+
run: sudo apt-get install -y doxygen
14+
1215
- name: Build
1316
run: |
1417
cd doc/nrf-bm

‎doc/nrf-bm/api/api.rst

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
.. nrf_bm_api:
2+
3+
API documentation
4+
#################
5+
6+
.. contents::
7+
:local:
8+
:depth: 2
9+
10+
.. _api_libs:
11+
12+
Libraries
13+
*********
14+
15+
Bluetooth LE Connection Parameter library
16+
=========================================
17+
18+
.. doxygengroup:: ble_conn_params
19+
:inner:
20+
21+
Bluetooth LE MCUmgr Service library
22+
===================================
23+
24+
.. doxygengroup:: ble_mcumgr
25+
:inner:
26+
27+
Bluetooth LE Nordic UART Service library
28+
========================================
29+
30+
.. doxygengroup:: ble_nus
31+
:inner:
32+
33+
Bluetooth LE advertising library
34+
================================
35+
36+
.. doxygengroup:: ble_adv
37+
:inner:
38+
39+
Advertising and Scan Response Data Encoder
40+
------------------------------------------
41+
42+
.. doxygengroup:: ble_sdk_lib_advdata
43+
:inner:
44+
45+
Bare Metal Zephyr Memory Storage (ZMS)
46+
======================================
47+
48+
.. doxygengroup:: bm_zms
49+
:inner:
50+
51+
Bare Metal Buttons library
52+
==========================
53+
54+
.. doxygengroup:: bm_buttons
55+
:inner:
56+
57+
Bare Metal Storage library
58+
==========================
59+
60+
.. doxygengroup:: bm_storage
61+
:inner:
62+
63+
Bare Metal Storage library backend
64+
----------------------------------
65+
66+
.. doxygengroup:: bm_storage_backend
67+
:inner:
68+
69+
Bare Metal Timer library
70+
========================
71+
72+
.. doxygengroup:: bm_timer
73+
:inner:
74+
75+
Bare Metal Low Power UART with EasyDMA driver
76+
=============================================
77+
78+
.. doxygengroup:: bm_lpuarte
79+
:inner:
80+
81+
Bare Metal Event Scheduler library
82+
==================================
83+
84+
.. doxygengroup:: event_scheduler
85+
:inner:
86+
87+
Queued Writes module
88+
====================
89+
90+
.. doxygengroup:: ble_qwr
91+
:inner:
92+
93+
Sensor data simulator library
94+
=============================
95+
96+
.. doxygengroup:: sensorsim
97+
:inner:
98+
99+
Record Access Control Point
100+
===========================
101+
102+
.. doxygengroup:: ble_racp
103+
:inner:
104+
105+
GATT Queue
106+
==========
107+
108+
.. doxygengroup:: ble_gq
109+
:inner:
110+
111+
Services
112+
********
113+
114+
Battery Service
115+
===============
116+
117+
.. doxygengroup:: ble_bas
118+
:inner:
119+
120+
Continuous Glucose Monitoring Service
121+
=====================================
122+
123+
.. doxygengroup:: ble_cgms
124+
:inner:
125+
126+
Device Information Service
127+
==========================
128+
129+
.. doxygengroup:: ble_dis
130+
:inner:
131+
132+
Heart Rate Service
133+
==================
134+
135+
.. doxygengroup:: ble_hrs
136+
:inner:
137+
138+
LED Button Service
139+
==================
140+
141+
.. doxygengroup:: ble_lbs
142+
:inner:
143+
144+
SoftDevice Handler
145+
******************
146+
147+
.. doxygengroup:: nrf_sdh
148+
:inner:
149+
150+
Utils
151+
*****
152+
153+
nRF Error Codes
154+
===============
155+
156+
.. doxygengroup:: nrf_error
157+
:inner:
158+
159+
Service UUID definitions
160+
========================
161+
162+
.. doxygengroup:: UUID_SERVICES
163+
:inner:
164+
165+
Characteristic UUID definitions
166+
===============================
167+
168+
.. doxygengroup:: UUID_CHARACTERISTICS
169+
:inner:
170+
171+
Bluetooth LE Date Time characteristic type
172+
==========================================
173+
174+
.. doxygengroup:: ble_sdk_srv_date_time
175+
:inner:

‎doc/nrf-bm/conf.py

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,22 @@
2626
# Add any Sphinx extension module names here, as strings. They can be
2727
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
2828
# ones.
29-
extensions = ['sphinx.ext.intersphinx', 'sphinx_tabs.tabs']
29+
extensions = ['sphinx.ext.intersphinx', 'sphinx_tabs.tabs', 'breathe']
3030

3131
rst_epilog = """
3232
.. include:: /substitutions.txt
3333
.. include:: /links.txt
3434
.. include:: /shortcuts.txt
3535
"""
3636

37+
# Options for breathe ---------------------------------------------------------
38+
breathe_projects = {
39+
"nRF Connect SDK Bare Metal option API": "doxygen/nrf-bm_api_xml/",
40+
}
41+
breathe_default_project = "nRF Connect SDK Bare Metal option API"
42+
breathe_domain_by_extension = {"h": "c", "c": "c"}
43+
breathe_separate_member_pages = True
44+
3745
# Add any paths that contain templates here, relative to this directory.
3846
templates_path = ['_templates']
3947

‎doc/nrf-bm/doxygen/mainpage.dox

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/**
2-
@mainpage nRF Connect SDK Bare Metal option 0.1.0 API documentation
2+
@mainpage nRF Connect SDK Bare Metal option 0.8.0 API documentation
33

44
@details API documentation built from header files in the nRF Connect SDK Bare Metal option repository.
55

‎doc/nrf-bm/doxygen/nrf-bm.doxyfile

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ PROJECT_NAME = "nRF Connect SDK Bare Metal option API"
4848
# could be handy for archiving the generated documentation or if some version
4949
# control system is used.
5050

51-
PROJECT_NUMBER = 0.1.0
51+
PROJECT_NUMBER = 0.8.0
5252

5353
# Using the PROJECT_BRIEF tag one can provide an optional one line description
5454
# for a project that appears at the top of each page and should give viewer a
@@ -74,7 +74,7 @@ PROJECT_ICON =
7474
# entered, it will be relative to the location where Doxygen was started. If
7575
# left blank the current directory will be used.
7676

77-
OUTPUT_DIRECTORY = html
77+
OUTPUT_DIRECTORY = doxygen
7878

7979
# If the CREATE_SUBDIRS tag is set to YES then Doxygen will create up to 4096
8080
# sub-directories (in 2 levels) under the output directory of each output format
@@ -180,7 +180,7 @@ FULL_PATH_NAMES = YES
180180
# will be relative from the directory where Doxygen is started.
181181
# This tag requires that the tag FULL_PATH_NAMES is set to YES.
182182

183-
STRIP_FROM_PATH = ../../../include
183+
STRIP_FROM_PATH = ../../../
184184

185185
# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
186186
# path mentioned in the documentation of a class, which tells the reader which
@@ -651,7 +651,7 @@ SHOW_HEADERFILE = YES
651651
# the files that are included by a file in the documentation of that file.
652652
# The default value is: YES.
653653

654-
SHOW_INCLUDE_FILES = YES
654+
SHOW_INCLUDE_FILES = NO
655655

656656
# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
657657
# grouped member an include statement to the documentation, telling the reader
@@ -997,7 +997,7 @@ INPUT_FILE_ENCODING =
997997
# be provided as Doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
998998
# *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice.
999999

1000-
FILE_PATTERNS = *.h
1000+
FILE_PATTERNS = *.h, *.dox
10011001

10021002
# The RECURSIVE tag can be used to specify whether or not subdirectories should
10031003
# be searched for input files as well.
@@ -2223,7 +2223,7 @@ GENERATE_XML = YES
22232223
# The default directory is: xml.
22242224
# This tag requires that the tag GENERATE_XML is set to YES.
22252225

2226-
XML_OUTPUT = xml
2226+
XML_OUTPUT = nrf-bm_api_xml
22272227

22282228
# If the XML_PROGRAMLISTING tag is set to YES, Doxygen will dump the program
22292229
# listings (including syntax highlighting and cross-referencing information) to

‎doc/nrf-bm/gen_docs.py

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,41 @@
106106
print(f"File not found: {file_path}")
107107
exit()
108108

109+
# Prepare Doxygen XML output for Breathe
110+
111+
# Save the current directory
112+
original_dir = os.getcwd()
113+
114+
# Path to the Doxyfile
115+
doxyfile_dir = os.path.abspath('doxygen')
116+
doxyfile_path = os.path.join(doxyfile_dir, 'nrf-bm.doxyfile')
117+
118+
# Change to the directory containing the Doxyfile
119+
os.chdir(doxyfile_dir)
120+
121+
# Run Doxygen
122+
print("Running Doxygen...")
123+
call(['doxygen', 'nrf-bm.doxyfile'])
124+
125+
# Change back to the original directory
126+
os.chdir(original_dir)
127+
128+
# Path to the Doxygen output directory
129+
doxygen_output_dir = os.path.abspath('doxygen/doxygen/nrf-bm_api_xml')
130+
131+
# Destination directory for Doxygen XML files within the Sphinx source
132+
doxygen_dest_dir = os.path.join(source_dir, 'doxygen/nrf-bm_api_xml')
133+
134+
# Copy Doxygen XML output to the Sphinx source directory
135+
if os.path.exists(doxygen_output_dir):
136+
if os.path.exists(doxygen_dest_dir):
137+
shutil.rmtree(doxygen_dest_dir) # Remove the existing directory if it exists
138+
shutil.copytree(doxygen_output_dir, doxygen_dest_dir)
139+
print(f"Copied Doxygen XML files to {doxygen_dest_dir}")
140+
else:
141+
print("Doxygen output directory not found.")
142+
exit()
143+
109144
# Run Sphinx
110145
call(["sphinx-build", "-b", "html", source_dir, "_build/html"])
111146

‎doc/nrf-bm/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,4 @@ The |BMlong| is a distinct repository that incorporates elements from the existi
4141
app_dev/dfu/index.rst
4242
release_notes.rst
4343
s115_docs.rst
44+
api/api.rst

‎doc/nrf-bm/requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ Sphinx
22
sphinx_rtd_theme
33
sphinx-tabs>=3.4
44
sphinx-togglebutton
5+
Breathe

0 commit comments

Comments
 (0)