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"] header [shape="rectangle" label="c header\ncomments"]
xml [shape="rectangle" label="XML"] xml [shape="rectangle" label="XML"]
html [shape="rectangle" label="HTML\nweb site"] html [shape="rectangle" label="HTML\nweb site"]
sphinx[shape="ellipse" label="sphinx +\nbreathe,\ndocutils"] sphinx[shape="ellipse" label="sphinx +\ndocutils"]
images -> sphinx images -> sphinx
rst -> sphinx rst -> sphinx
conf -> 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, The reStructuredText files are processed by the Sphinx documentation system,
and make use of the breathe extension for including the doxygen-generated API and make use of the doxygen-generated API material.
material. Additional tools are required to generate the Additional tools are required to generate the
documentation locally, as described in the following sections. documentation locally, as described in the following sections.
.. _documentation-processors: .. _documentation-processors:
@ -242,24 +242,6 @@ build the documentation directly from there:
# To generate PDF output # To generate PDF output
make pdf 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 Developer-mode Document Building
******************************** ********************************