[RFC] doc: replace breathe with Sphinx-Doxygen bridge

doc/_extensions/zephyr/doxybridge.py

@@ -0,0 +1,133 @@
+"""
+Copyright (c) 2021 Nordic Semiconductor ASA
+SPDX-License-Identifier: Apache-2.0
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict
+
+from docutils import nodes
+
+from sphinx.addnodes import pending_xref
+from sphinx.application import Sphinx
+from sphinx.transforms.post_transforms import SphinxPostTransform
+from sphinx.util import logging
+
+import xml.etree.ElementTree as ET
+
+
+logger = logging.getLogger(__name__)
+
+
+KIND_D2S = {
+    "define": "macro",
+    "variable": "var",
+    "typedef": "type",
+    "enum": "enum",
+    "function": "func",
+}
+"""Mapping between Doxygen memberdef kind and Sphinx kinds"""
+
+
+class DoxygenReferencer(SphinxPostTransform):
+
+    default_priority = 5
+
+    def run(self, **kwargs: Any) -> None:
+        for node in self.document.traverse(pending_xref):
+            if node.get("refdomain") != "c":
+                continue
+
+            reftype = node.get("reftype")
+            entry = self.app.env.doxybridge_cache.get(reftype)
+            if not entry:
+                continue
+
+            reftarget = node.get("reftarget")
+            id = entry.get(reftarget)
+            if not id:
+                continue
+
+            if reftype in ("struct", "union"):
+                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())
+
+            node.replace_self([refnode])
+
+
+def doxygen_parse(app: Sphinx) -> None:
+    app.env.doxybridge_cache = {
+        "macro": {},
+        "var": {},
+        "type": {},
+        "enum": {},
+        "func": {},
+        "union": {},
+        "struct": {},
+    }
+
+    xmldir = Path(app.config.doxybridge_dir) / "xml"
+    for file in xmldir.glob("*_8[a-z].xml"):
+        root = ET.parse(file).getroot()
+
+        compounddef = root.find("compounddef")
+        if not compounddef or compounddef.attrib["kind"] != "file":
+            logger.warning(f"Unexpected file content in {file}")
+            continue
+
+        memberdefs = compounddef.findall(".//memberdef")
+        for memberdef in memberdefs:
+            kind = KIND_D2S.get(memberdef.attrib["kind"])
+            if not kind:
+                logger.warning(f"Unsupported kind: {kind}")
+                continue
+
+            id = memberdef.attrib["id"]
+            name = memberdef.find("name").text
+
+            app.env.doxybridge_cache[kind][name] = id
+
+        innerclasses = compounddef.findall(".//innerclass")
+        for innerclass in innerclasses:
+            refid = innerclass.get("refid")
+            if refid.startswith("union"):
+                kind = "union"
+            elif refid.startswith("struct"):
+                kind = "struct"
+            else:
+                continue
+
+            name = innerclass.text
+            app.env.doxybridge_cache[kind][name] = refid
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_config_value("doxybridge_dir", None, "env")
+
+    app.add_post_transform(DoxygenReferencer)
+    app.connect("builder-inited", doxygen_parse)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

doc/conf.py

@@ -67,7 +67,6 @@
 # -- General configuration ------------------------------------------------
 
 extensions = [
-    "breathe",
     "sphinx.ext.todo",
     "sphinx.ext.extlinks",
     "sphinx.ext.autodoc",
@@ -80,6 +79,7 @@
     "sphinx_tabs.tabs",
     "zephyr.warnings_filter",
     "zephyr.doxyrunner",
+    "zephyr.doxybridge",
     "notfound.extension",
     "zephyr.external_content",
 ]
@@ -183,30 +183,9 @@
 doxyrunner_fmt = True
 doxyrunner_fmt_vars = {"ZEPHYR_BASE": str(ZEPHYR_BASE), "ZEPHYR_VERSION": version}
 
-# -- Options for Breathe plugin -------------------------------------------
+# -- Options for zephyr.doxybridge 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",
-    "__deprecated",
-    "__may_alias",
-    "__used",
-    "__unused",
-    "__weak",
-    "__attribute_const__",
-    "__DEPRECATED_MACRO",
-    "FUNC_NORETURN",
-    "__subsystem",
-]
-c_id_attributes = cpp_id_attributes
+doxybridge_dir = doxyrunner_outdir
 
 # -- Options for html_redirect plugin -------------------------------------
 

doc/guides/debug_tools/coredump.rst

@@ -340,6 +340,6 @@ the following needs to be done:
 API documentation
 *****************
 
-.. doxygengroup:: coredump_apis
 
-.. doxygengroup:: arch-coredump
+
+

doc/guides/debug_tools/thread-analyzer.rst

@@ -84,4 +84,4 @@ Configure this module using the following options.
 API documentation
 *****************
 
-.. doxygengroup:: thread_analyzer
+

doc/guides/debug_tools/tracing/index.rst

@@ -351,85 +351,85 @@ API
 Common
 ======
 
-.. doxygengroup:: tracing_apis
+
 
 Threads
 =======
 
-.. doxygengroup:: thread_tracing_apis
+
 
 
 Work Queues
 ===========
 
-.. doxygengroup:: work_tracing_apis
+
 
 
 Poll
 ====
 
-.. doxygengroup:: poll_tracing_apis
+
 
 Semaphore
 =========
 
-.. doxygengroup:: sem_tracing_apis
+
 
 Mutex
 =====
 
-.. doxygengroup:: mutex_tracing_apis
+
 
 Condition Variables
 ===================
 
-.. doxygengroup:: condvar_tracing_apis
+
 
 Queues
 ======
 
-.. doxygengroup:: queue_tracing_apis
+
 
 FIFO
 ====
 
-.. doxygengroup:: fifo_tracing_apis
+
 
 LIFO
 ====
-.. doxygengroup:: lifo_tracing_apis
+
 
 Stacks
 ======
 
-.. doxygengroup:: stack_tracing_apis
+
 
 Message Queues
 ==============
 
-.. doxygengroup:: msgq_tracing_apis
+
 
 Mailbox
 =======
 
-.. doxygengroup:: mbox_tracing_apis
+
 
 Pipes
 ======
 
-.. doxygengroup:: pipe_tracing_apis
+
 
 Heaps
 =====
 
-.. doxygengroup:: heap_tracing_apis
+
 
 Memory Slabs
 ============
 
-.. doxygengroup:: mslab_tracing_apis
+
 
 Timers
 ======
 
-.. doxygengroup:: timer_tracing_apis
+

doc/guides/porting/arch.rst

@@ -841,41 +841,41 @@ API Reference
 Timing
 ======
 
-.. doxygengroup:: arch-timing
+
 
 Threads
 =======
 
-.. doxygengroup:: arch-threads
 
-.. doxygengroup:: arch-tls
+
+
 
 Power Management
 ================
 
-.. doxygengroup:: arch-pm
+
 
 Symmetric Multi-Processing
 ==========================
 
-.. doxygengroup:: arch-smp
+
 
 Interrupts
 ==========
 
-.. doxygengroup:: arch-irq
+
 
 Userspace
 =========
 
-.. doxygengroup:: arch-userspace
+
 
 Memory Management
 =================
 
-.. doxygengroup:: arch-mmu
+
 
 Miscellaneous Architecture APIs
 ===============================
 
-.. doxygengroup:: arch-misc
+

doc/guides/test/ztest.rst

@@ -299,7 +299,7 @@ API reference
 Running tests
 =============
 
-.. doxygengroup:: ztest_test
+
 
 Assertions
 ==========
@@ -318,7 +318,7 @@ Example output for a failed macro from
     Assertion failed at main.c:62: test_get_single_buffer: Invalid refcount (buf->ref not equal to 2)
     Aborted at unit test function
 
-.. doxygengroup:: ztest_assert
+
 
 Mocking
 =======
@@ -337,7 +337,7 @@ expect the values ``a=2`` and ``b=3``, and telling ``returns_int`` to return
    :language: c
    :linenos:
 
-.. doxygengroup:: ztest_mock
+
 
 Customizing Test Output
 ***********************

doc/reference/audio/codec.rst

@@ -18,4 +18,4 @@ Related configuration options:
 API Reference
 *************
 
-.. doxygengroup:: audio_codec_interface
+

doc/reference/audio/dmic.rst

@@ -18,4 +18,4 @@ Related configuration options:
 API Reference
 *************
 
-.. doxygengroup:: audio_dmic_interface
+

doc/reference/audio/i2s.rst

@@ -21,4 +21,4 @@ Related configuration options:
 API Reference
 *************
 
-.. doxygengroup:: i2s_interface
+