doc: add breathe and import existing Doxygen groups

In Zephyr, most APIs in Doxygen are also imported in Sphinx using the
breathe exstension. While breathe is de-facto unmaintained, this comes
handy to have an integrated documentation experience. User is warned to
check the maintainership status of breathe, because Doxygen in
standalone mode (also offered) may be enough.

Signed-off-by: Gerard Marull-Paretas <[email protected]>

Author: gmarull

doc/Doxyfile

@@ -1003,7 +1003,7 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = z_impl_*
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -2177,7 +2177,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

doc/conf.py

@@ -14,13 +14,11 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ['sphinx.ext.intersphinx']
+extensions = ['sphinx.ext.intersphinx', 'breathe']
 
 templates_path = ['_templates']
 exclude_patterns = ['_build_sphinx', 'Thumbs.db', '.DS_Store']
 
-
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
@@ -30,3 +28,13 @@
 # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html
 
 intersphinx_mapping = {'zephyr': ('https://docs.zephyrproject.org/latest/', None)}
+
+## -- Options for Breathe ----------------------------------------------------
+# https://breathe.readthedocs.io/en/latest/index.html
+#
+# WARNING: please, check breathe maintainership status before using this
+# extension in production!
+
+breathe_projects = {'example-application': '_build_doxygen/xml'}
+breathe_default_project = 'example-application'
+breathe_default_members = ('members', )

doc/drivers/blink.rst

@@ -0,0 +1,14 @@
+Blink
+=====
+
+.. doxygengroup:: drivers_blink
+
+Driver operations
+-----------------
+
+.. doxygengroup:: drivers_blink_ops
+
+Public API
+----------
+
+.. doxygengroup:: drivers_blink_api

doc/drivers/index.rst

@@ -0,0 +1,9 @@
+Drivers
+=======
+
+.. doxygengroup:: drivers
+
+.. toctree::
+    :maxdepth: 1
+
+    blink

doc/index.rst

@@ -8,7 +8,10 @@ Welcome to Example Application's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
+
+   drivers/index
+   lib/index
 
 This is a simple Sphinx documentation setup for ``example-application``. You can
 reference Zephyr documentation items, like

doc/lib/custom.rst

@@ -0,0 +1,11 @@
+Custom
+======
+
+.. doxygengroup:: lib_custom
+    :desc-only:
+
+Public API
+----------
+
+.. doxygengroup:: lib_custom
+    :content-only:

doc/lib/index.rst

@@ -0,0 +1,9 @@
+Libraries
+=========
+
+.. doxygengroup:: lib
+
+.. toctree::
+    :maxdepth: 1
+
+    custom

doc/requirements.txt

@@ -1 +1,2 @@
 Sphinx
+breathe