Skip to content

doc: doc generation: remove breathe references #77233

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 21, 2024
Merged

doc: doc generation: remove breathe references #77233

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 3 additions & 21 deletions doc/contribute/documentation/generation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
********************************

Expand Down