Describe the bug
Since Zephyr upstream goes on to v4.0 and thus removes some major functional features for processing all the spreaded RST documentation in code we are no longer able to rebuild our own downstream documentation sets for Bridle. The following functions have been removed without replacement:
zephyrproject-rtos/zephyr#73671 – Sphinx extension breathe deactivated: Zephyr no longer render Doxygen content inside of Sphinx. See:
zephyrproject-rtos/zephyr#77023 – Sphinx extension zephyr.warnings_filter deactivated: This is no longer needed as Zephyr link directly to Doxygen pages since breathe was removed. See:
zephyrproject-rtos/zephyr#79160 – Catches also foreign boards (in context of the new "Zephyr domain" in Sphinx all external boards from Bridle downstream), but can't handle such boards because of wrong relative folder to the hard coded ZEPHYR_BASE_DIR. See:
ninja: Entering directory `build/bridle-doc'
ninja: error: '/.../workspace/zephyr/doc/known-warnings.txt', needed by 'zephyr/known-
warnings.txt', missing and no known rule to make it
Expected behavior
Rebuild all documentation sats as before.
Impact
Showstopper: can't release next Bridle version.
Logs and console output
See above.
Screenshots
None.
Development Environment (please complete the following information):
OS: Linux
Toolchain: West v1.3.0, CMake v3.28.1, Sphinx v8.1.3, Doxygen v1.9.8
Branch: main, Zephyr v4.0.0-rc1 (upstream main)
Additional context
None.
Procedure
Error correction is increasingly proving to be a more complex challenge than initially expected. We will therefore proceed via several pull requests in the following individual steps.
[x] Fix the new board catalog generator to skip foreign boards (the Bridle boards) on our own Zephyr main line mirror repository at https://github.com/tiacsys/zephyr.
[ ] Copy and own the always removed zephyr.warnings_filter Sphinx extension as bridle.warnings_filter – as long as Bridle have to rebuild different documentation sets by a splitted strategy (apartly the document inventory first and then the other documents at all that dependent to other inventories), Bridle have to expect and tolerate warnings of unknown or invalid references to "other" inter-Sphinx documents. In the past it was a good practice to filter out such expected warnings explicitly by the warnings_filter.
[ ] Remove the dependency to the Sphinx extension breathe (and interbreathe) also for the Bridle documentation set in the same manner as Zephyr already done. The Bridle documentation will swap to the new functionality by the Zephyr provided Sphinx extensions zephyr.doxybridge and maybe zephyr.doxytooltip
Describe the bug Since Zephyr upstream goes on to v4.0 and thus removes some major functional features for processing all the spreaded RST documentation in code we are no longer able to rebuild our own downstream documentation sets for Bridle. The following functions have been removed without replacement:
breathedeactivated: Zephyr no longer render Doxygen content inside of Sphinx. See:zephyr.warnings_filterdeactivated: This is no longer needed as Zephyr link directly to Doxygen pages sincebreathewas removed. See:doc/known-warnings.txt)Additional changes inside the Zephyr upstream documentation build process that Bridle now have to or should respect:
zephyr.link-roles. See:ZEPHYR_BASE_DIR. See:DOCS_HTML_DIRtoOUTPUT_DIR. See:DOCS_HTML_DIR. See:To Reproduce Steps to reproduce the behavior:
mainbranchcmake -Bbuild/bridle-doc -GNinja bridle/docninja -Cbuild/bridle-doc zephyr-doxygenninja -Cbuild/bridle-doc bridle-doxygenninja -Cbuild/bridle-doc build-allExpected behavior Rebuild all documentation sats as before.
Impact Showstopper: can't release next Bridle version.
Logs and console output See above.
Screenshots None.
Development Environment (please complete the following information):
main, Zephyr v4.0.0-rc1 (upstreammain)Additional context None.
Procedure
Error correction is increasingly proving to be a more complex challenge than initially expected. We will therefore proceed via several pull requests in the following individual steps.
zephyr.warnings_filterSphinx extension asbridle.warnings_filter– as long as Bridle have to rebuild different documentation sets by a splitted strategy (apartly the document inventory first and then the other documents at all that dependent to other inventories), Bridle have to expect and tolerate warnings of unknown or invalid references to "other" inter-Sphinx documents. In the past it was a good practice to filter out such expected warnings explicitly by thewarnings_filter.breathe(andinterbreathe) also for the Bridle documentation set in the same manner as Zephyr already done. The Bridle documentation will swap to the new functionality by the Zephyr provided Sphinx extensionszephyr.doxybridgeand maybezephyr.doxytooltip