From 9f141597ee063fc0d8e32cf420ea99b604b62878 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Tue, 4 Jun 2024 10:01:22 +0200 Subject: [PATCH 1/6] samples: drivers: clock_control_litex: clean up use of c domain roles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Simplify how the code sample refers to C objects to be less dependant on Breathe. Signed-off-by: Benjamin Cabé --- samples/drivers/clock_control_litex/README.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/samples/drivers/clock_control_litex/README.rst b/samples/drivers/clock_control_litex/README.rst index 0a7d7878cb2b5..eb01b39b9949c 100644 --- a/samples/drivers/clock_control_litex/README.rst +++ b/samples/drivers/clock_control_litex/README.rst @@ -45,12 +45,9 @@ This configuration defines 2 clock outputs: ``clk0`` and ``clk1`` with default f Driver Usage ************ -The driver is interfaced with the :ref:`Clock Control API ` function ``clock_control_on()`` and a LiteX driver specific structure: +The driver is interfaced with the :ref:`Clock Control API ` function ``clock_control_on()`` and a LiteX driver specific structure (:c:struct:`litex_clk_setup`). -.. doxygenstruct:: litex_clk_setup - :project: Zephyr - -| To change clock parameter it is needed to cast a pointer to structure ``litex_clk_setup`` onto ``clock_control_subsys_t`` and use it with ``clock_control_on()``. +| To change clock parameter it is needed to cast a pointer to structure :c:struct:`litex_clk_setup` onto :c:type:`clock_control_subsys_t` and use it with :c:func:`clock_control_on()`. | This code will try to set on ``clk0`` frequency 50MHz, 90 degrees of phase offset and 75% duty cycle. .. code-block:: c From e78d83eddef9b80dda39a2548bdf1a9d1c97bd54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Mon, 3 Jun 2024 15:19:42 +0200 Subject: [PATCH 2/6] doc: Use basic ..doxygengroup syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Do not pass options to doxygengroup to rationalize usage and be less dependent on Breathe. Signed-off-by: Benjamin Cabé --- doc/build/dts/api/api.rst | 1 - doc/connectivity/bluetooth/api/mesh/blob.rst | 2 -- doc/connectivity/bluetooth/api/mesh/blob_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/blob_flash.rst | 1 - doc/connectivity/bluetooth/api/mesh/blob_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/dfd_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/dfu.rst | 6 ------ doc/connectivity/bluetooth/api/mesh/dfu_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/dfu_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/lcd_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/lcd_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/od_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/od_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/priv_beacon_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/priv_beacon_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/rpr_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/rpr_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/sar_cfg_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/sar_cfg_srv.rst | 2 -- doc/connectivity/bluetooth/api/mesh/srpl_cli.rst | 2 -- doc/connectivity/bluetooth/api/mesh/srpl_srv.rst | 2 -- doc/hardware/peripherals/mdio.rst | 1 - doc/kernel/memory_management/demand_paging.rst | 3 --- doc/kernel/memory_management/shared_multi_heap.rst | 1 - doc/kernel/services/other/version.rst | 1 - 27 files changed, 54 deletions(-) diff --git a/doc/build/dts/api/api.rst b/doc/build/dts/api/api.rst index e76ad997fb519..63017d4d66781 100644 --- a/doc/build/dts/api/api.rst +++ b/doc/build/dts/api/api.rst @@ -359,7 +359,6 @@ system-wide settings. The :c:func:`DT_CHOSEN()` macro can be used to get a node identifier for a chosen node. .. doxygengroup:: devicetree-generic-chosen - :project: Zephyr Zephyr-specific chosen nodes **************************** diff --git a/doc/connectivity/bluetooth/api/mesh/blob.rst b/doc/connectivity/bluetooth/api/mesh/blob.rst index 8395026afe4e6..a22fb3d142338 100644 --- a/doc/connectivity/bluetooth/api/mesh/blob.rst +++ b/doc/connectivity/bluetooth/api/mesh/blob.rst @@ -191,5 +191,3 @@ API reference 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 0d533109830ad..b993454719b15 100644 --- a/doc/connectivity/bluetooth/api/mesh/blob_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/blob_cli.rst @@ -126,5 +126,3 @@ API reference ************* .. doxygengroup:: bt_mesh_blob_cli - :project: Zephyr - :members: diff --git a/doc/connectivity/bluetooth/api/mesh/blob_flash.rst b/doc/connectivity/bluetooth/api/mesh/blob_flash.rst index 5966fe3562be9..294dc4ea0b194 100644 --- a/doc/connectivity/bluetooth/api/mesh/blob_flash.rst +++ b/doc/connectivity/bluetooth/api/mesh/blob_flash.rst @@ -32,4 +32,3 @@ API Reference ************* .. doxygengroup:: bt_mesh_blob_io_flash - :project: Zephyr diff --git a/doc/connectivity/bluetooth/api/mesh/blob_srv.rst b/doc/connectivity/bluetooth/api/mesh/blob_srv.rst index 0d13e92148e75..ac829fc14d5f3 100644 --- a/doc/connectivity/bluetooth/api/mesh/blob_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/blob_srv.rst @@ -96,5 +96,3 @@ 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 8efc040a56cf6..9ffcc91df71b8 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfd_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfd_srv.rst @@ -37,5 +37,3 @@ 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 5140d2ae36d65..926754ab0f022 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfu.rst @@ -371,13 +371,7 @@ API reference This section lists the types common to the Device Firmware Update mesh models. .. doxygengroup:: bt_mesh_dfd - :project: Zephyr - :members: .. 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 71952999caae8..ab6f04596e154 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfu_cli.rst @@ -12,5 +12,3 @@ 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 fdccbba639cce..3c7dd31d58956 100644 --- a/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/dfu_srv.rst @@ -128,5 +128,3 @@ 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 96189e21dd31c..b64f5241e88d8 100644 --- a/doc/connectivity/bluetooth/api/mesh/lcd_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/lcd_cli.rst @@ -22,5 +22,3 @@ 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 f67b31c27f835..aeb772044de91 100644 --- a/doc/connectivity/bluetooth/api/mesh/lcd_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/lcd_srv.rst @@ -35,5 +35,3 @@ 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 e419acb7572cf..d7a8c9daa190e 100644 --- a/doc/connectivity/bluetooth/api/mesh/od_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/od_cli.rst @@ -33,5 +33,3 @@ 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 3c2f993bb302d..e9944dc10b17f 100644 --- a/doc/connectivity/bluetooth/api/mesh/od_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/od_srv.rst @@ -24,5 +24,3 @@ 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 4648b4495cd46..de1f02b52598c 100644 --- a/doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/op_agg_cli.rst @@ -27,5 +27,3 @@ 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 81bd4a90b22b6..336180251f3e7 100644 --- a/doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/op_agg_srv.rst @@ -28,5 +28,3 @@ 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 c9bcc8e5eb1c0..2d6063a1f95ec 100644 --- a/doc/connectivity/bluetooth/api/mesh/priv_beacon_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/priv_beacon_cli.rst @@ -31,5 +31,3 @@ 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 62450634a317f..5376cd11a9815 100644 --- a/doc/connectivity/bluetooth/api/mesh/priv_beacon_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/priv_beacon_srv.rst @@ -34,5 +34,3 @@ 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 8a87939541aab..eef5b371abf85 100644 --- a/doc/connectivity/bluetooth/api/mesh/rpr_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/rpr_cli.rst @@ -138,5 +138,3 @@ 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 e51d3c8fac911..7e7d7c6c04ed2 100644 --- a/doc/connectivity/bluetooth/api/mesh/rpr_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/rpr_srv.rst @@ -34,5 +34,3 @@ API reference ************* .. doxygengroup:: bt_mesh_rpr_srv - :project: Zephyr - :members: diff --git a/doc/connectivity/bluetooth/api/mesh/sar_cfg_cli.rst b/doc/connectivity/bluetooth/api/mesh/sar_cfg_cli.rst index 1e2ab6c47a16f..9883d935b5513 100644 --- a/doc/connectivity/bluetooth/api/mesh/sar_cfg_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/sar_cfg_cli.rst @@ -37,5 +37,3 @@ API reference ************* .. doxygengroup:: bt_mesh_sar_cfg_cli - :project: Zephyr - :members: diff --git a/doc/connectivity/bluetooth/api/mesh/sar_cfg_srv.rst b/doc/connectivity/bluetooth/api/mesh/sar_cfg_srv.rst index 4280fae135067..00e65231c66d0 100644 --- a/doc/connectivity/bluetooth/api/mesh/sar_cfg_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/sar_cfg_srv.rst @@ -27,5 +27,3 @@ API reference ************* .. doxygengroup:: bt_mesh_sar_cfg_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 a5a9b7ba47f8e..ed594390e2056 100644 --- a/doc/connectivity/bluetooth/api/mesh/srpl_cli.rst +++ b/doc/connectivity/bluetooth/api/mesh/srpl_cli.rst @@ -31,5 +31,3 @@ 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 ad8a26e4c44a9..c3567c5f616ea 100644 --- a/doc/connectivity/bluetooth/api/mesh/srpl_srv.rst +++ b/doc/connectivity/bluetooth/api/mesh/srpl_srv.rst @@ -30,5 +30,3 @@ API reference ************* .. doxygengroup:: bt_mesh_sol_pdu_rpl_srv - :project: Zephyr - :members: diff --git a/doc/hardware/peripherals/mdio.rst b/doc/hardware/peripherals/mdio.rst index 24a8e5ecb5acf..d665f5cef7e42 100644 --- a/doc/hardware/peripherals/mdio.rst +++ b/doc/hardware/peripherals/mdio.rst @@ -17,4 +17,3 @@ API Reference ************* .. doxygengroup:: mdio_interface - :project: Zephyr diff --git a/doc/kernel/memory_management/demand_paging.rst b/doc/kernel/memory_management/demand_paging.rst index 54eb12baac0a7..b07d2d99042d0 100644 --- a/doc/kernel/memory_management/demand_paging.rst +++ b/doc/kernel/memory_management/demand_paging.rst @@ -183,16 +183,13 @@ API Reference ************* .. doxygengroup:: mem-demand-paging - :project: Zephyr Eviction Algorithm APIs ======================= .. doxygengroup:: mem-demand-paging-eviction - :project: Zephyr Backing Store APIs ================== .. doxygengroup:: mem-demand-paging-backing-store - :project: Zephyr diff --git a/doc/kernel/memory_management/shared_multi_heap.rst b/doc/kernel/memory_management/shared_multi_heap.rst index cc5101ae1fbfe..ff6387e682b60 100644 --- a/doc/kernel/memory_management/shared_multi_heap.rst +++ b/doc/kernel/memory_management/shared_multi_heap.rst @@ -79,4 +79,3 @@ The API does not enforce any attributes, but at least it defines the two most common ones: :c:enumerator:`SMH_REG_ATTR_CACHEABLE` and :c:enumerator:`SMH_REG_ATTR_NON_CACHEABLE`. .. doxygengroup:: shared_multi_heap - :project: Zephyr diff --git a/doc/kernel/services/other/version.rst b/doc/kernel/services/other/version.rst index dde8f69300400..fba1bfbb6efa5 100644 --- a/doc/kernel/services/other/version.rst +++ b/doc/kernel/services/other/version.rst @@ -9,4 +9,3 @@ API Reference ************** .. doxygengroup:: version_apis - :content-only: From e1fee367476b550af23fc7d5663db7f16081345f Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Mon, 25 Oct 2021 17:05:17 +0200 Subject: [PATCH 3/6] doc: deactivate breathe extension Deactivate breathe extension from docs. Signed-off-by: Gerard Marull-Paretas --- doc/conf.py | 28 ---------------------------- doc/known-warnings.txt | 22 ---------------------- doc/requirements.txt | 1 - 3 files changed, 51 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index c9cd9699c28f8..709f3ea46806f 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -73,7 +73,6 @@ # -- General configuration ------------------------------------------------ extensions = [ - "breathe", "sphinx_rtd_theme", "sphinx.ext.todo", "sphinx.ext.extlinks", @@ -249,33 +248,6 @@ doxyrunner_fmt_vars = {"ZEPHYR_BASE": str(ZEPHYR_BASE), "ZEPHYR_VERSION": version} doxyrunner_outdir_var = "DOXY_OUT" -# -- Options for Breathe plugin ------------------------------------------- - -breathe_projects = {"Zephyr": str(doxyrunner_outdir / "xml")} -breathe_default_project = "Zephyr" -breathe_domain_by_extension = { - "h": "c", - "c": "c", -} -breathe_show_enumvalue_initializer = True -breathe_default_members = ("members", ) - -cpp_id_attributes = [ - "__syscall", - "__syscall_always_inline", - "__deprecated", - "__may_alias", - "__used", - "__unused", - "__weak", - "__attribute_const__", - "__DEPRECATED_MACRO", - "FUNC_NORETURN", - "__subsystem", - "ALWAYS_INLINE", -] -c_id_attributes = cpp_id_attributes - # -- Options for html_redirect plugin ------------------------------------- html_redirect_pages = redirects.REDIRECTS diff --git a/doc/known-warnings.txt b/doc/known-warnings.txt index 35a0ed60b03ed..72ad03d55d577 100644 --- a/doc/known-warnings.txt +++ b/doc/known-warnings.txt @@ -1,24 +1,2 @@ # Each line should contain the regular expression of a known Sphinx warning # that should be filtered out - -# Function and (enum or struct) name -.*Duplicate C declaration.*\n.*'\.\. c:.*:: flash_img_check'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: fs_statvfs'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*dmic_trigger.*'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: dma_config'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: net_if_mcast_monitor'.* - -# Struct and typedef name -.*Duplicate C declaration.*\n.*'\.\. c:.*:: zsock_fd_set'.* - -# Function and extern function -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv4_addr_mask_cmp.*'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv4_is_addr_bcast.*'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv4_addr_lookup.*'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv6_addr_lookup.*'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*net_if_ipv6_maddr_lookup.*'.* - -# Common field names -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*struct in_addr.*'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*struct in6_addr.*'.* -.*Duplicate C declaration.*\n.*'\.\. c:.*:: .*struct net_if.*'.* diff --git a/doc/requirements.txt b/doc/requirements.txt index 55cf8de629759..468be6969c192 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,6 +1,5 @@ # DOC: used to generate docs -breathe>=4.34 sphinx sphinx_rtd_theme~=2.0 sphinx-tabs From a9ea10e34e39f0c6a6c2e6d48ff5d4ac1d44d308 Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Mon, 25 Oct 2021 17:06:17 +0200 Subject: [PATCH 4/6] doc: extensions: add doxybridge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an initial version of doxybridge, an extension that allows to use Sphinx C domain to automatically reference Doxygen pages. It also introduces minimal support for `.. doxygengroup` directive, which effectively links to the group's Doxygen page. Co-authored-by: Benjamin Cabé Signed-off-by: Gerard Marull-Paretas Signed-off-by: Benjamin Cabé --- doc/_extensions/zephyr/domain.py | 4 +- doc/_extensions/zephyr/doxybridge.py | 235 +++++++++++++++++++++++++++ doc/_static/css/custom.css | 12 ++ 3 files changed, 249 insertions(+), 2 deletions(-) create mode 100644 doc/_extensions/zephyr/doxybridge.py diff --git a/doc/_extensions/zephyr/domain.py b/doc/_extensions/zephyr/domain.py index 66327f9c7adcd..f40b03a6c516e 100644 --- a/doc/_extensions/zephyr/domain.py +++ b/doc/_extensions/zephyr/domain.py @@ -48,7 +48,6 @@ """ from typing import Any, Dict, Iterator, List, Tuple -from breathe.directives.content_block import DoxygenGroupDirective from docutils import nodes from docutils.nodes import Node from docutils.parsers.rst import Directive, directives @@ -59,6 +58,7 @@ from sphinx.transforms.post_transforms import SphinxPostTransform from sphinx.util import logging from sphinx.util.nodes import NodeMatcher, make_refnode +from zephyr.doxybridge import DoxygenGroupDirective from zephyr.gh_utils import gh_link_get_url import json @@ -323,7 +323,7 @@ def setup(app): app.add_transform(ConvertCodeSampleNode) app.add_post_transform(ProcessRelatedCodeSamplesNode) - # monkey-patching of Breathe's DoxygenGroupDirective + # monkey-patching of the DoxygenGroupDirective app.add_directive("doxygengroup", CustomDoxygenGroupDirective, override=True) return { diff --git a/doc/_extensions/zephyr/doxybridge.py b/doc/_extensions/zephyr/doxybridge.py new file mode 100644 index 0000000000000..b15b1fc2f9ac7 --- /dev/null +++ b/doc/_extensions/zephyr/doxybridge.py @@ -0,0 +1,235 @@ +""" +Copyright (c) 2021 Nordic Semiconductor ASA +Copyright (c) 2024 The Linux Foundation +SPDX-License-Identifier: Apache-2.0 +""" + +import os +from typing import Any, Dict + +import concurrent.futures + +from docutils import nodes + +from sphinx import addnodes +from sphinx.application import Sphinx +from sphinx.transforms.post_transforms import SphinxPostTransform +from sphinx.util import logging +from sphinx.util.docutils import SphinxDirective +from sphinx.domains.c import CXRefRole + +import doxmlparser +from doxmlparser.compound import DoxCompoundKind, DoxMemberKind + +logger = logging.getLogger(__name__) + + +KIND_D2S = { + DoxMemberKind.DEFINE: "macro", + DoxMemberKind.VARIABLE: "var", + DoxMemberKind.TYPEDEF: "type", + DoxMemberKind.ENUM: "enum", + DoxMemberKind.FUNCTION: "func", +} + + +class DoxygenGroupDirective(SphinxDirective): + has_content = False + required_arguments = 1 + optional_arguments = 0 + + def run(self): + + desc_node = addnodes.desc() + desc_node["domain"] = "c" + desc_node["objtype"] = "group" + + title_signode = addnodes.desc_signature() + group_xref = addnodes.pending_xref( + "", + refdomain="c", + reftype="group", + reftarget=self.arguments[0], + refwarn=True, + ) + group_xref += nodes.Text(self.arguments[0]) + title_signode += group_xref + + desc_node.append(title_signode) + + return [desc_node] + + +class DoxygenReferencer(SphinxPostTransform): + """Mapping between Doxygen memberdef kind and Sphinx kinds""" + + default_priority = 5 + + def run(self, **kwargs: Any) -> None: + for node in self.document.traverse(addnodes.pending_xref): + if node.get("refdomain") != "c": + continue + + reftype = node.get("reftype") + + # "member", "data" and "var" are equivalent as per Sphinx documentation for C domain + if reftype in ("member", "data"): + reftype = "var" + + entry = self.app.env.doxybridge_cache.get(reftype) + if not entry: + continue + + reftarget = node.get("reftarget").replace(".", "::").rstrip("()") + id = entry.get(reftarget) + if not id: + if reftype == "func": + # macros are sometimes referenced as functions, so try that + id = self.app.env.doxybridge_cache.get("macro").get(reftarget) + if not id: + continue + else: + continue + + if reftype in ("struct", "union", "group"): + doxygen_target = f"{id}.html" + else: + split = id.split("_") + doxygen_target = f"{'_'.join(split[:-1])}.html#{split[-1][1:]}" + + doxygen_target = str(self.app.config.doxybridge_dir) + "/html/" + doxygen_target + + doc_dir = os.path.dirname(self.document.get("source")) + doc_dest = os.path.join( + self.app.outdir, + os.path.relpath(doc_dir, self.app.srcdir), + ) + rel_uri = os.path.relpath(doxygen_target, doc_dest) + + refnode = nodes.reference("", "", internal=True, refuri=rel_uri, reftitle="") + + refnode.append(node[0].deepcopy()) + + if reftype == "group": + refnode["classes"].append("doxygroup") + title = self.app.env.doxybridge_group_titles.get(reftarget, "group") + refnode[0] = nodes.Text(title) + + node.replace_self([refnode]) + + +def parse_members(sectiondef): + cache = {} + + for memberdef in sectiondef.get_memberdef(): + kind = KIND_D2S.get(memberdef.get_kind()) + if not kind: + continue + + id = memberdef.get_id() + if memberdef.get_kind() == DoxMemberKind.VARIABLE: + name = memberdef.get_qualifiedname() or memberdef.get_name() + else: + name = memberdef.get_name() + + cache.setdefault(kind, {})[name] = id + + if memberdef.get_kind() == DoxMemberKind.ENUM: + for enumvalue in memberdef.get_enumvalue(): + enumname = enumvalue.get_name() + enumid = enumvalue.get_id() + cache.setdefault("enumerator", {})[enumname] = enumid + + return cache + + +def parse_sections(compounddef): + cache = {} + + for sectiondef in compounddef.get_sectiondef(): + members = parse_members(sectiondef) + for kind, data in members.items(): + cache.setdefault(kind, {}).update(data) + + return cache + + +def parse_compound(inDirName, baseName) -> Dict: + rootObj = doxmlparser.compound.parse(inDirName + "/" + baseName + ".xml", True) + cache = {} + group_titles = {} + + for compounddef in rootObj.get_compounddef(): + name = compounddef.get_compoundname() + id = compounddef.get_id() + kind = None + if compounddef.get_kind() == DoxCompoundKind.STRUCT: + kind = "struct" + elif compounddef.get_kind() == DoxCompoundKind.UNION: + kind = "union" + elif compounddef.get_kind() == DoxCompoundKind.GROUP: + kind = "group" + group_titles[name] = compounddef.get_title() + + if kind: + cache.setdefault(kind, {})[name] = id + + sections = parse_sections(compounddef) + for kind, data in sections.items(): + cache.setdefault(kind, {}).update(data) + + return cache, group_titles + + +def parse_index(app: Sphinx, inDirName): + rootObj = doxmlparser.index.parse(inDirName + "/index.xml", True) + compounds = rootObj.get_compound() + + with concurrent.futures.ProcessPoolExecutor() as executor: + futures = [ + executor.submit(parse_compound, inDirName, compound.get_refid()) + for compound in compounds + ] + for future in concurrent.futures.as_completed(futures): + cache, group_titles = future.result() + for kind, data in cache.items(): + app.env.doxybridge_cache.setdefault(kind, {}).update(data) + app.env.doxybridge_group_titles.update(group_titles) + + +def doxygen_parse(app: Sphinx) -> None: + if not app.env.doxygen_input_changed: + return + + app.env.doxybridge_cache = { + "macro": {}, + "var": {}, + "type": {}, + "enum": {}, + "enumerator": {}, + "func": {}, + "union": {}, + "struct": {}, + "group": {}, + } + + app.env.doxybridge_group_titles = {} + + parse_index(app, str(app.config.doxybridge_dir / "xml")) + + +def setup(app: Sphinx) -> Dict[str, Any]: + app.add_config_value("doxybridge_dir", None, "env") + + app.add_directive("doxygengroup", DoxygenGroupDirective) + + app.add_role_to_domain("c", "group", CXRefRole()) + + app.add_post_transform(DoxygenReferencer) + app.connect("builder-inited", doxygen_parse) + + return { + "version": "0.1", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/doc/_static/css/custom.css b/doc/_static/css/custom.css index b820543f3dedb..97a00d9e2c1b9 100644 --- a/doc/_static/css/custom.css +++ b/doc/_static/css/custom.css @@ -953,3 +953,15 @@ dark-mode-toggle::part(toggleLabel){ #search-se-menu ul li.selected .fa-check { display: inline; } + +.doxygroup::after { + content: 'Doxygen'; + display: inline-block; + background-color: var(--admonition-note-title-background-color); + color: var(--admonition-note-title-color); + padding: 2px 8px; + border-radius: 12px; + margin-left: 8px; + font-size: 0.875em; + font-weight: bold; +} \ No newline at end of file From 3e9676a8d2d9f3d5fd529f9ee34cd697f58aa7b7 Mon Sep 17 00:00:00 2001 From: Gerard Marull-Paretas Date: Mon, 25 Oct 2021 17:07:42 +0200 Subject: [PATCH 5/6] doc: enable doxybridge Enable the doxybridge extension. Signed-off-by: Gerard Marull-Paretas --- doc/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 709f3ea46806f..d0280fb560f3e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -88,6 +88,7 @@ "sphinx_sitemap", "zephyr.warnings_filter", "zephyr.doxyrunner", + "zephyr.doxybridge", "zephyr.gh_utils", "zephyr.manifest_projects_table", "notfound.extension", @@ -248,6 +249,10 @@ doxyrunner_fmt_vars = {"ZEPHYR_BASE": str(ZEPHYR_BASE), "ZEPHYR_VERSION": version} doxyrunner_outdir_var = "DOXY_OUT" +# -- Options for zephyr.doxybridge plugin --------------------------------- + +doxybridge_dir = doxyrunner_outdir + # -- Options for html_redirect plugin ------------------------------------- html_redirect_pages = redirects.REDIRECTS From 32f96b3693436f9b17060fe0255c877f0e58fd71 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjamin=20Cab=C3=A9?= Date: Tue, 4 Jun 2024 11:07:57 +0200 Subject: [PATCH 6/6] doc: zephyr_domain: Show code samples after doxygengroups MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Minor cosmetic update post Breathe removal Signed-off-by: Benjamin Cabé --- doc/_extensions/zephyr/domain.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/_extensions/zephyr/domain.py b/doc/_extensions/zephyr/domain.py index f40b03a6c516e..92bb50cfd7825 100644 --- a/doc/_extensions/zephyr/domain.py +++ b/doc/_extensions/zephyr/domain.py @@ -310,7 +310,7 @@ def run(self) -> List[Node]: nodes = super().run() if self.config.zephyr_breathe_insert_related_samples: - return [RelatedCodeSamplesNode(id=self.arguments[0]), *nodes] + return [*nodes, RelatedCodeSamplesNode(id=self.arguments[0])] else: return nodes