From fa9961c6b02e9f4c892e26597b4542015cad1f5b Mon Sep 17 00:00:00 2001 From: Ederson de Souza Date: Fri, 25 Aug 2023 13:58:52 -0700 Subject: [PATCH] doc: Generate develop/api/overview.rst API table from doxygen A new extension, api_overview.py, is used to, leveraging doxygen's Python module doxmlparser, parse the doxygen generated XML files. All groups ('defgroup' and 'addtogroup' tags) are collected, alongside their 'version' and 'since' info. From there, a new Sphinx directive `api-overview-table` is populated, including the name of the group, and if available, their 'since' and 'version' information. Signed-off-by: Ederson de Souza --- doc/CMakeLists.txt | 1 + doc/_extensions/zephyr/api_overview.py | 161 ++++++++ doc/conf.py | 4 + doc/develop/api/overview.rst | 378 +----------------- .../misc/timeaware_gpio/timeaware_gpio.h | 2 + include/zephyr/llext/llext.h | 2 + include/zephyr/net/conn_mgr_connectivity.h | 2 + include/zephyr/net/ieee802154.h | 4 + include/zephyr/net/ieee802154_mgmt.h | 2 + include/zephyr/net/ieee802154_radio.h | 2 + include/zephyr/retention/blinfo.h | 2 + 11 files changed, 183 insertions(+), 377 deletions(-) create mode 100644 doc/_extensions/zephyr/api_overview.py diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 5cfce578a4a9e82..3f8224a3d1be535 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -140,6 +140,7 @@ set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${GEN_DEVICETREE_ add_doc_target( html COMMAND ${CMAKE_COMMAND} -E env ${SPHINX_ENV} + PYTHONPATH=${ZEPHYR_BASE}/doc/_extensions/zephyr${SEP}$ENV{PYTHONPATH} ${SPHINXBUILD} -b html -c ${DOCS_CFG_DIR} diff --git a/doc/_extensions/zephyr/api_overview.py b/doc/_extensions/zephyr/api_overview.py new file mode 100644 index 000000000000000..fb73f5fb7ded981 --- /dev/null +++ b/doc/_extensions/zephyr/api_overview.py @@ -0,0 +1,161 @@ +# Copyright (c) 2023 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +import doxmlparser + +from docutils import nodes +from doxmlparser.compound import DoxCompoundKind +from pathlib import Path +from sphinx.application import Sphinx +from sphinx.util.docutils import SphinxDirective +from typing import Any, Dict + + +class ApiOverview(SphinxDirective): + r""" + This is a Zephyr directive to generate a table containing an overview + of all APIs. This table will show the API name, version and since which + version it is present - all information extracted from Doxygen XML output. + + It is exclusively used by the doc/develop/api/overview.rst page. + + Configuration options: + api_overview_doxygen_xml_dir: Doxygen xml output directory + api_overview_doxygen_base_url: Doxygen base html directory + """ + + def run(self): + return [self.env.api_overview_table] + + +spacer = ' ' + + +def get_group(innergroup, all_groups): + return [ + g + for g in all_groups + if g.get_compounddef()[0].get_id() == innergroup.get_refid() + ][0] + + +def visit_group(app, group, all_groups, rows, indent=0): + version = since = url = "" + cdef = group.get_compounddef()[0] + ssects = [ + s for p in cdef.get_detaileddescription().get_para() for s in p.get_simplesect() + ] + for sect in ssects: + if sect.get_kind() == "since": + since = sect.get_para()[0].get_valueOf_() + elif sect.get_kind() == "version": + version = sect.get_para()[0].get_valueOf_() + + url_base = app.config.api_overview_doxygen_base_url.rstrip("/") + url = f"{url_base}/{cdef.get_id()}.html" + + title = cdef.get_title() + + row_node = nodes.row() + + # Next entry will contain the spacer and the link with API name + entry = nodes.entry() + span = nodes.raw(text=spacer.format(indent=indent), format="html") + entry += span + + # API name with link + inline = nodes.inline() + reference = nodes.reference(text=title, refuri=url) + reference.attributes["internal"] = True + inline += reference + entry += inline + row_node += entry + + # Finally, add version and since + for cell in [version, since]: + entry = nodes.entry() + entry += nodes.Text(cell) + row_node += entry + rows.append(row_node) + + for innergroup in cdef.get_innergroup(): + visit_group( + app, get_group(innergroup, all_groups), all_groups, rows, indent + 16 + ) + + +def parse_xml_dir(dir_name): + groups = [] + root = doxmlparser.index.parse(f"{dir_name}/index.xml", True) + for compound in root.get_compound(): + if compound.get_kind() == DoxCompoundKind.GROUP: + file_name = f"{dir_name}/{compound.get_refid()}.xml" + groups.append(doxmlparser.compound.parse(file_name, True)) + + return groups + + +def generate_table(app, toplevel, groups): + table = nodes.table() + tgroup = nodes.tgroup() + + thead = nodes.thead() + thead_row = nodes.row() + for header_name in ["API", "Version", "Since"]: + colspec = nodes.colspec() + tgroup += colspec + + entry = nodes.entry() + entry += nodes.Text(header_name) + thead_row += entry + thead += thead_row + tgroup += thead + + rows = [] + tbody = nodes.tbody() + for t in toplevel: + visit_group(app, t, groups, rows) + tbody.extend(rows) + tgroup += tbody + + table += tgroup + + return table + + +def sync_contents(app: Sphinx) -> None: + if app.config.doxyrunner_outdir: + doxygen_out_dir = Path(app.config.doxyrunner_outdir) + else: + doxygen_out_dir = Path(app.outdir) / "_doxygen" + + doxygen_xml_dir = doxygen_out_dir / "xml" + groups = parse_xml_dir(doxygen_xml_dir) + + toplevel = [ + g + for g in groups + if g.get_compounddef()[0].get_id() + not in [ + i.get_refid() + for h in [j.get_compounddef()[0].get_innergroup() for j in groups] + for i in h + ] + ] + + app.builder.env.api_overview_table = generate_table(app, toplevel, groups) + + +def setup(app) -> Dict[str, Any]: + app.add_config_value("api_overview_doxygen_xml_dir", "html/doxygen/xml", "env") + app.add_config_value("api_overview_doxygen_base_url", "../../doxygen/html", "env") + + app.add_directive("api-overview-table", ApiOverview) + + app.connect("builder-inited", sync_contents) + + return { + "version": "0.1", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/doc/conf.py b/doc/conf.py index 4c153e7a2e7aefd..0243505cd0f60ef 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -89,6 +89,7 @@ "sphinx_togglebutton", "zephyr.external_content", "zephyr.domain", + "zephyr.api_overview", ] # Only use SVG converter when it is really needed, e.g. LaTeX. @@ -334,6 +335,9 @@ linkcheck_workers = 10 linkcheck_anchors = False +# -- Options for zephyr.api_overview -------------------------------------- + +api_overview_doxygen_base_url = "../../doxygen/html" def setup(app): # theme customizations diff --git a/doc/develop/api/overview.rst b/doc/develop/api/overview.rst index 642d7b807c3864b..49a641d353b0464 100644 --- a/doc/develop/api/overview.rst +++ b/doc/develop/api/overview.rst @@ -7,380 +7,4 @@ The table lists Zephyr's APIs and information about them, including their current :ref:`stability level `. More details about API changes between major releases are available in the :ref:`zephyr_release_notes`. -.. Keep this list sorted by the name of the API as it appears - in the HTML, *NOT* the :ref: label - -.. list-table:: - :header-rows: 1 - - * - API - - Status - - Version Introduced - - * - :ref:`adc_api` - - Stable - - 1.0 - - * - :ref:`audio_codec_api` - - Experimental - - 1.13 - - * - :ref:`audio_dmic_api` - - Experimental - - 1.13 - - * - :ref:`auxdisplay_api` - - Experimental - - 3.4 - - * - :ref:`barriers_api` - - Experimental - - 3.4 - - * - :ref:`blinfo_api` - - Experimental - - 3.5 - - * - :ref:`bluetooth_api` - - Stable - - 1.0 - - * - :ref:`clock_control_api` - - Stable - - 1.0 - - * - :ref:`coap_sock_interface` - - Unstable - - 1.10 - - * - :ref:`conn_mgr_docs` - - Experimental - - 3.4.0 - - * - :ref:`can_api` - - Stable - - 1.14 - - * - :ref:`can_transceiver_api` - - Experimental - - 3.1 - - * - :ref:`charger_api` - - Experimental - - 3.5 - - * - :ref:`counter_api` - - Unstable - - 1.14 - - * - :ref:`crypto_api` - - Stable - - 1.7 - - * - :ref:`dac_api` - - Unstable - - 2.3 - - * - :ref:`dai_api` - - Experimental - - 3.1 - - * - :ref:`dma_api` - - Stable - - 1.5 - - * - :ref:`device_model_api` - - Stable - - 1.0 - - * - :ref:`devicetree_api` - - Stable - - 2.2 - - * - :ref:`disk_access_api` - - Stable - - 1.6 - - * - :ref:`display_api` - - Unstable - - 1.14 - - * - :ref:`ec_host_cmd_backend_api` - - Experimental - - 2.4 - - * - :ref:`edac_api` - - Unstable - - 2.5 - - * - :ref:`eeprom_api` - - Stable - - 2.1 - - * - :ref:`entropy_api` - - Stable - - 1.10 - - * - :ref:`file_system_api` - - Stable - - 1.5 - - * - :ref:`flash_api` - - Stable - - 1.2 - - * - :ref:`fcb_api` - - Stable - - 1.11 - - * - :ref:`fuel_gauge_api` - - Experimental - - 3.3 - - * - :ref:`flash_map_api` - - Stable - - 1.11 - - * - :ref:`gnss_api` - - Experimental - - 3.6 - - * - :ref:`gpio_api` - - Stable - - 1.0 - - * - :ref:`hwinfo_api` - - Stable - - 1.14 - - * - :ref:`i2c_eeprom_target_api` - - Stable - - 1.13 - - * - :ref:`i2c_api` - - Stable - - 1.0 - - * - :ref:`i2c-target-api` - - Experimental - - 1.12 - - * - :ref:`i2s_api` - - Stable - - 1.9 - - * - :ref:`i3c_api` - - Experimental - - 3.2 - - * - :ref:`ieee802154_driver_api` - - Unstable - - 1.0 - - * - :ref:`ieee802154_l2_api` - - Unstable - - 1.0 - - * - :ref:`ieee802154_mgmt_api` - - Unstable - - 1.0 - - * - :ref:`input` - - Experimental - - 3.4 - - * - :ref:`ipm_api` - - Stable - - 1.0 - - * - :ref:`kscan_api` - - Stable - - 2.1 - - * - :ref:`kernel_api` - - Stable - - 1.0 - - * - :ref:`led_api` - - Stable - - 1.12 - - * - :ref:`lwm2m_interface` - - Unstable - - 1.9 - - * - :ref:`llext` - - Experimental - - 3.5 - - * - :ref:`logging_api` - - Stable - - 1.13 - - * - :ref:`lora_api` - - Experimental - - 2.2 - - * - :ref:`lorawan_api` - - Experimental - - 2.5 - - * - :ref:`mbox_api` - - Experimental - - 1.0 - - * - :ref:`mcu_mgr` - - Stable - - 1.11 - - * - :ref:`mqtt_socket_interface` - - Unstable - - 1.14 - - * - :ref:`mipi_dsi_api` - - Experimental - - 3.1 - - * - :ref:`misc_api` - - Stable - - 1.0 - - * - :ref:`networking_api` - - Stable - - 1.0 - - * - :ref:`nvs_api` - - Stable - - 1.12 - - * - :ref:`peci_api` - - Stable - - 2.1 - - * - :ref:`ps2_api` - - Stable - - 2.1 - - * - :ref:`pwm_api` - - Stable - - 1.0 - - * - :ref:`pinctrl_api` - - Experimental - - 3.0 - - * - :ref:`pm_api` - - Experimental - - 1.2 - - * - :ref:`random_api` - - Stable - - 1.0 - - * - :ref:`regulator_api` - - Experimental - - 2.4 - - * - :ref:`reset_api` - - Experimental - - 3.1 - - * - :ref:`retained_mem_api` - - Experimental - - 3.4 - - * - :ref:`retention_api` - - Experimental - - 3.4 - - * - :ref:`rtc_api` - - Experimental - - 3.4 - - * - :ref:`rtio_api` - - Experimental - - 3.2 - - * - :ref:`smbus_api` - - Experimental - - 3.4 - - * - :ref:`spi_api` - - Stable - - 1.0 - - * - :ref:`sensor_api` - - Stable - - 1.2 - - * - :ref:`settings_api` - - Stable - - 1.12 - - * - :ref:`shell_api` - - Stable - - 1.14 - - * - :ref:`stream_flash` - - Experimental - - 2.3 - - * - :ref:`sdhc_api` - - Experimental - - 3.1 - - * - :ref:`task_wdt_api` - - Unstable - - 2.5 - - * - :ref:`tcpc_api` - - Experimental - - 3.1 - - * - :ref:`tgpio_api` - - Experimental - - 3.5 - - * - :ref:`uart_api` - - Stable - - 1.0 - - * - :ref:`UART async ` - - Unstable - - 1.14 - - * - :ref:`usb_api` - - Stable - - 1.5 - - * - :ref:`usbc_api` - - Experimental - - 3.3 - - * - :ref:`usermode_api` - - Stable - - 1.11 - - * - :ref:`usbc_vbus_api` - - Experimental - - 3.3 - - * - :ref:`util_api` - - Experimental - - 2.4 - - * - :ref:`video_api` - - Stable - - 2.1 - - * - :ref:`w1_api` - - Experimental - - 3.2 - - * - :ref:`watchdog_api` - - Stable - - 1.0 - - * - :ref:`zdsp_api` - - Experimental - - 3.3 +.. api-overview-table:: diff --git a/include/zephyr/drivers/misc/timeaware_gpio/timeaware_gpio.h b/include/zephyr/drivers/misc/timeaware_gpio/timeaware_gpio.h index 68c305f9e1840e7..f9d0f6a8e2c6884 100644 --- a/include/zephyr/drivers/misc/timeaware_gpio/timeaware_gpio.h +++ b/include/zephyr/drivers/misc/timeaware_gpio/timeaware_gpio.h @@ -14,6 +14,8 @@ /** * @brief Time-aware GPIO Interface * @defgroup tgpio_interface Time-aware GPIO Interface + * @since 3.5 + * @version 0.1.0 * @ingroup io_interfaces * @{ */ diff --git a/include/zephyr/llext/llext.h b/include/zephyr/llext/llext.h index 6afb48682be5e2b..a1cdc1ce5c68c4c 100644 --- a/include/zephyr/llext/llext.h +++ b/include/zephyr/llext/llext.h @@ -20,6 +20,8 @@ extern "C" { /** * @brief Linkable loadable extensions * @defgroup llext Linkable loadable extensions + * @since 3.5 + * @version 0.1.0 * @ingroup os_services * @{ */ diff --git a/include/zephyr/net/conn_mgr_connectivity.h b/include/zephyr/net/conn_mgr_connectivity.h index 0d92cdbf8d7245f..7796d3371f94d12 100644 --- a/include/zephyr/net/conn_mgr_connectivity.h +++ b/include/zephyr/net/conn_mgr_connectivity.h @@ -25,6 +25,8 @@ extern "C" { /** * @brief Connection Manager Connectivity API * @defgroup conn_mgr_connectivity Connection Manager Connectivity API + * @since 3.4.0 + * @version 0.1.0 * @ingroup networking * @{ */ diff --git a/include/zephyr/net/ieee802154.h b/include/zephyr/net/ieee802154.h index e4ef8bba6f8fd63..927a9036db3e3d4 100644 --- a/include/zephyr/net/ieee802154.h +++ b/include/zephyr/net/ieee802154.h @@ -26,6 +26,8 @@ extern "C" { /** * @defgroup ieee802154 IEEE 802.15.4 and Thread APIs + * @since 1.0 + * @version 0.8.0 * @ingroup connectivity * * @brief IEEE 802.15.4 native and OpenThread L2, configuration, management and @@ -76,6 +78,8 @@ extern "C" { /** * @defgroup ieee802154_l2 IEEE 802.15.4 L2 + * @since 1.0 + * @version 0.8.0 * @ingroup ieee802154 * * @brief IEEE 802.15.4 L2 APIs diff --git a/include/zephyr/net/ieee802154_mgmt.h b/include/zephyr/net/ieee802154_mgmt.h index 3711e818d241904..1f08c0b73c063be 100644 --- a/include/zephyr/net/ieee802154_mgmt.h +++ b/include/zephyr/net/ieee802154_mgmt.h @@ -23,6 +23,8 @@ extern "C" { /** * @defgroup ieee802154_mgmt IEEE 802.15.4 Net Management + * @since 1.0 + * @version 0.8.0 * @ingroup ieee802154 * * @brief IEEE 802.15.4 net management library diff --git a/include/zephyr/net/ieee802154_radio.h b/include/zephyr/net/ieee802154_radio.h index 9c2aa3816e42862..e67e264464ce444 100644 --- a/include/zephyr/net/ieee802154_radio.h +++ b/include/zephyr/net/ieee802154_radio.h @@ -29,6 +29,8 @@ extern "C" { /** * @defgroup ieee802154_driver IEEE 802.15.4 Drivers + * @since 1.0 + * @version 0.8.0 * @ingroup ieee802154 * * @brief IEEE 802.15.4 driver API diff --git a/include/zephyr/retention/blinfo.h b/include/zephyr/retention/blinfo.h index 0ecd051771f9c31..e3a6e6b570d7a00 100644 --- a/include/zephyr/retention/blinfo.h +++ b/include/zephyr/retention/blinfo.h @@ -27,6 +27,8 @@ extern "C" { /** * @brief Bootloader info interface * @defgroup bootloader_info_interface Bootloader info interface + * @since 3.5 + * @version 0.1.0 * @ingroup retention_api * @{ */