From 56a691078ecc8a6dfac26033257850e6c0ec4bdd Mon Sep 17 00:00:00 2001 From: Simon Hein Date: Mon, 19 Aug 2024 14:02:26 +0200 Subject: [PATCH] doc: doc generation: remove breathe references Remove the references to the breathe extension in the Schematic of the documentation build process graph and the filtering expected warnings section. Signed-off-by: Simon Hein --- doc/contribute/documentation/generation.rst | 24 +++------------------ 1 file changed, 3 insertions(+), 21 deletions(-) diff --git a/doc/contribute/documentation/generation.rst b/doc/contribute/documentation/generation.rst index f51eb59e44e..013decd0455 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 +\nbreathe,\ndocutils"] + sphinx[shape="ellipse" label="sphinx +\ndocutils"] images -> sphinx rst -> sphinx conf -> sphinx @@ -65,8 +65,8 @@ The project's documentation contains the following items: The reStructuredText files are processed by the Sphinx documentation system, -and make use of the breathe extension for including the doxygen-generated API -material. Additional tools are required to generate the +and make use of the doxygen-generated API material. +Additional tools are required to generate the documentation locally, as described in the following sections. .. _documentation-processors: @@ -242,24 +242,6 @@ build the documentation directly from there: # To generate PDF output make pdf -Filtering expected 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 -``zephyr.warnings_filter`` and it is located at -``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/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 -- Nested elements (e.g. in a struct or union) can not share the same name - Developer-mode Document Building ********************************