michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: doc generation: remove breathe references

Browse source 
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 <Shein@baumer.com>
This commit is contained in:
Simon Hein 2024-08-19 14:02:26 +02:00 • committed by Fabio Baltieri
commit 56a691078e
1 changed files with 3 additions and 21 deletions
Download patch file Download diff file Expand all files Collapse all files

24
doc/contribute/documentation/generation.rst
View file

@ -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
********************************