diff --git a/doc/_extensions/zephyr/doxyrunner.py b/doc/_extensions/zephyr/doxyrunner.py index 8ab68cc754397..8bd10e63a97c9 100644 --- a/doc/_extensions/zephyr/doxyrunner.py +++ b/doc/_extensions/zephyr/doxyrunner.py @@ -9,7 +9,7 @@ ============ This Sphinx plugin can be used to run Doxygen build as part of the Sphinx build -process. It is meant to be used with other plugins such as ``docleaf`` in order +process. It is meant to be used with other plugins such as ``breathe`` in order to improve the user experience. The principal features offered by this plugin are: diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css index a357621205aac..da9f379d41d6d 100644 --- a/doc/_static/css/custom.css +++ b/doc/_static/css/custom.css @@ -843,13 +843,13 @@ kbd, .kbd, background-color: var(--navbar-scrollbar-active-color); } -/* Docleaf tweaks */ +/* Breathe tweaks */ .rst-content .section > dl > dd { margin-left: 0; } -.rst-content p.docleaf-sectiondef-title { +.rst-content p.breathe-sectiondef-title { font-size: 115%; color: var(--link-color); } diff --git a/doc/conf.py b/doc/conf.py index 51b4dd593dfde..551bb599b0afa 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -67,7 +67,7 @@ # -- General configuration ------------------------------------------------ extensions = [ - "docleaf.doxygen", + "breathe", "sphinx.ext.todo", "sphinx.ext.extlinks", "sphinx.ext.autodoc", @@ -211,17 +211,16 @@ doxyrunner_fmt_vars = {"ZEPHYR_BASE": str(ZEPHYR_BASE), "ZEPHYR_VERSION": version} doxyrunner_outdir_var = "DOXY_OUT" -# -- Options for Docleaf plugin ------------------------------------------- +# -- Options for Breathe plugin ------------------------------------------- -docleaf_projects = {"Zephyr": {"xml": str(doxyrunner_outdir / "xml"), "root": "../"}} -docleaf_default_project = "Zephyr" -docleaf_domain_by_extension = { +breathe_projects = {"Zephyr": str(doxyrunner_outdir / "xml")} +breathe_default_project = "Zephyr" +breathe_domain_by_extension = { "h": "c", "c": "c", } -# Filters out any 'function' or 'variable' members that have 'all caps' names as -# they are likely unprocessed macro calls -docleaf_doxygen_skip = ["members:all_caps"] +breathe_show_enumvalue_initializer = True +breathe_default_members = ("members", ) cpp_id_attributes = [ "__syscall", diff --git a/doc/connectivity/bluetooth/api/mesh/blob.rst b/doc/connectivity/bluetooth/api/mesh/blob.rst index d36ba366ed449..069f1ac9c6351 100644 --- a/doc/connectivity/bluetooth/api/mesh/blob.rst +++ b/doc/connectivity/bluetooth/api/mesh/blob.rst @@ -127,3 +127,4 @@ This section contains types and defines common to the BLOB Transfer models. .. doxygengroup:: bt_mesh_blob :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/blob_cli.rst b/doc/connectivity/bluetooth/api/mesh/blob_cli.rst index 74ee8d43d6f92..6d926be1b5cac 100644 --- a/doc/connectivity/bluetooth/api/mesh/blob_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/blob_cli.rst @@ -93,3 +93,4 @@ API reference .. doxygengroup:: bt_mesh_blob_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/blob_srv.rst b/doc/connectivity/bluetooth/api/mesh/blob_srv.rst index b88cd364724f9..22c2540a3377f 100644 --- a/doc/connectivity/bluetooth/api/mesh/blob_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/blob_srv.rst @@ -67,3 +67,4 @@ API reference .. doxygengroup:: bt_mesh_blob_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/dfd_srv.rst b/doc/connectivity/bluetooth/api/mesh/dfd_srv.rst index 7c9c8c77a5878..a1912e3acfb93 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfd_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfd_srv.rst @@ -23,3 +23,4 @@ API reference .. doxygengroup:: bt_mesh_dfd_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/dfu.rst b/doc/connectivity/bluetooth/api/mesh/dfu.rst index b4dc456178f77..685aaf3cbd1de 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfu.rst @@ -221,6 +221,8 @@ This section lists the types common to the Device Firmware Update mesh models. .. doxygengroup:: bt_mesh_dfu :project: Zephyr + :members: .. doxygengroup:: bt_mesh_dfu_metadata :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/dfu_cli.rst b/doc/connectivity/bluetooth/api/mesh/dfu_cli.rst index 74a08ac0620e7..c4ea98770d93e 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfu_cli.rst @@ -11,3 +11,4 @@ API reference .. doxygengroup:: bt_mesh_dfu_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst b/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst index fa35e484f76f0..0b98b1ec067c2 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst @@ -68,3 +68,4 @@ API reference .. doxygengroup:: bt_mesh_dfu_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/lcd_cli.rst b/doc/connectivity/bluetooth/api/mesh/lcd_cli.rst index 6871b51abed45..27df2e493b216 100644 --- a/doc/connectivity/bluetooth/api/mesh/lcd_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/lcd_cli.rst @@ -17,3 +17,4 @@ API reference .. doxygengroup:: bt_mesh_large_comp_data_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/lcd_srv.rst b/doc/connectivity/bluetooth/api/mesh/lcd_srv.rst index cd10e3f84a4c3..df724974b86ae 100644 --- a/doc/connectivity/bluetooth/api/mesh/lcd_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/lcd_srv.rst @@ -27,3 +27,4 @@ API reference .. doxygengroup:: bt_mesh_large_comp_data_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/od_cli.rst b/doc/connectivity/bluetooth/api/mesh/od_cli.rst index 8d49d716b6d43..ea2deae79b9fd 100644 --- a/doc/connectivity/bluetooth/api/mesh/od_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/od_cli.rst @@ -26,3 +26,4 @@ API reference .. doxygengroup:: bt_mesh_od_priv_proxy_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/od_srv.rst b/doc/connectivity/bluetooth/api/mesh/od_srv.rst index e23d17c9d9518..241ce5f155cf2 100644 --- a/doc/connectivity/bluetooth/api/mesh/od_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/od_srv.rst @@ -25,3 +25,4 @@ API reference .. doxygengroup:: bt_mesh_od_priv_proxy_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst b/doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst index 80d5f52d13ece..23eb608391f95 100644 --- a/doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst @@ -27,3 +27,4 @@ API reference .. doxygengroup:: bt_mesh_op_agg_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst b/doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst index 25fbe8bb758a3..5d493cb45909c 100644 --- a/doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst @@ -29,3 +29,4 @@ API reference .. doxygengroup:: bt_mesh_op_agg_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/priv_beacon_cli.rst b/doc/connectivity/bluetooth/api/mesh/priv_beacon_cli.rst index ce81cfcd76faf..6a6f44b1387e9 100644 --- a/doc/connectivity/bluetooth/api/mesh/priv_beacon_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/priv_beacon_cli.rst @@ -33,3 +33,4 @@ API reference .. doxygengroup:: bt_mesh_priv_beacon_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/priv_beacon_srv.rst b/doc/connectivity/bluetooth/api/mesh/priv_beacon_srv.rst index 7728bede2a731..d69fe616e3802 100644 --- a/doc/connectivity/bluetooth/api/mesh/priv_beacon_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/priv_beacon_srv.rst @@ -36,3 +36,4 @@ API reference .. doxygengroup:: bt_mesh_priv_beacon_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/rpr_cli.rst b/doc/connectivity/bluetooth/api/mesh/rpr_cli.rst index aa4909a37b7c2..38cb8849f9e5d 100644 --- a/doc/connectivity/bluetooth/api/mesh/rpr_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/rpr_cli.rst @@ -129,3 +129,4 @@ API reference .. doxygengroup:: bt_mesh_rpr_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/rpr_srv.rst b/doc/connectivity/bluetooth/api/mesh/rpr_srv.rst index 9d966179e980b..f958ef31bd938 100644 --- a/doc/connectivity/bluetooth/api/mesh/rpr_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/rpr_srv.rst @@ -27,3 +27,4 @@ API reference .. doxygengroup:: bt_mesh_rpr_srv :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/srpl_cli.rst b/doc/connectivity/bluetooth/api/mesh/srpl_cli.rst index 5764d223c07b9..e940158dd2ef3 100644 --- a/doc/connectivity/bluetooth/api/mesh/srpl_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/srpl_cli.rst @@ -28,3 +28,4 @@ API reference .. doxygengroup:: bt_mesh_sol_pdu_rpl_cli :project: Zephyr + :members: diff --git a/doc/connectivity/bluetooth/api/mesh/srpl_srv.rst b/doc/connectivity/bluetooth/api/mesh/srpl_srv.rst index 8c897450bbb56..a8c5379e3052c 100644 --- a/doc/connectivity/bluetooth/api/mesh/srpl_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/srpl_srv.rst @@ -27,3 +27,4 @@ API reference .. doxygengroup:: bt_mesh_sol_pdu_rpl_srv :project: Zephyr + :members: diff --git a/doc/contribute/documentation/generation.rst b/doc/contribute/documentation/generation.rst index 756c1c2a70290..3701e86013856 100644 --- a/doc/contribute/documentation/generation.rst +++ b/doc/contribute/documentation/generation.rst @@ -52,7 +52,7 @@ The project's documentation contains the following items: header [shape="rectangle" label="c header\ncomments"] xml [shape="rectangle" label="XML"] html [shape="rectangle" label="HTML\nweb site"] - sphinx[shape="ellipse" label="sphinx +\ndocleaf,\ndocutils"] + sphinx[shape="ellipse" label="sphinx +\nbreathe,\ndocutils"] images -> sphinx rst -> sphinx conf -> sphinx @@ -65,7 +65,7 @@ The project's documentation contains the following items: The reStructuredText files are processed by the Sphinx documentation system, -and make use of the docleaf extension for including the doxygen-generated API +and make use of the breathe extension for including the doxygen-generated API material. Additional tools are required to generate the documentation locally, as described in the following sections. @@ -226,7 +226,7 @@ build the documentation directly from there: Filtering expected warnings *************************** -There are some known issues with Sphinx/Docleaf that generate Sphinx warnings +There are some known issues with Sphinx/Breathe that generate Sphinx warnings even though the input is valid C code. While these issues are being considered for fixing we have created a Sphinx extension that allows to filter them out based on a set of regular expressions. The extension is named @@ -234,8 +234,8 @@ based on a set of regular expressions. The extension is named ``doc/_extensions/zephyr/warnings_filter.py``. The warnings to be filtered out can be added to the ``doc/known-warnings.txt`` file. -The most common warning reported by Sphinx/Docleaf is related to duplicate C -declarations. This warning may be caused by different Sphinx/Docleaf issues: +The most common warning reported by Sphinx/Breathe is related to duplicate C +declarations. This warning may be caused by different Sphinx/Breathe issues: - Multiple declarations of the same object are not supported - Different objects (e.g. a struct and a function) can not share the same name diff --git a/doc/requirements.txt b/doc/requirements.txt index 2bd19422dca57..2d90048e16f90 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +1,6 @@ # DOC: used to generate docs -docleaf==0.8.1 +breathe>=4.34 sphinx~=6.2 sphinx_rtd_theme~=1.2 sphinx-tabs