[BUG] Can't build the documentation sets for Bridle and Zephyr anymore

[rexut]

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:

• Remove Breathe from doc infra zephyrproject-rtos/zephyr#73671 – Sphinx extension breathe deactivated: Zephyr no longer render Doxygen content inside of Sphinx. See:
  • zephyrproject-rtos/zephyr@259db8c
  • zephyrproject-rtos/zephyr@56a6910
  • zephyrproject-rtos/zephyr@a258ab3
• doc: extensions: drop warnings_filter 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@e28232d
  • zephyrproject-rtos/zephyr@259db8c (doc/known-warnings.txt)
• doc: doc generation: remove breathe references zephyrproject-rtos/zephyr#77233 – See:
  • zephyrproject-rtos/zephyr@56a6910

Additional changes inside the Zephyr upstream documentation build process that Bridle now have to or should respect:

• doc: _scripts: gen_devicetree_rest: add link to driver sources zephyrproject-rtos/zephyr#79259 – Our Devicetree documentation set depends now on the Sphinx extension zephyr.link-roles. See:
  • zephyrproject-rtos/zephyr@d224fa1
• RFC: doc: Add an interactive board catalog 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:
  • zephyrproject-rtos/zephyr@536d34f
  • zephyrproject-rtos/zephyr@c9b7104
  • zephyrproject-rtos/zephyr@ecb7c87 (!) "doc: boards: extensions: introduce zephyr:board role and directive"
  • zephyrproject-rtos/zephyr@5349902 (!) "doc: boards: extensions: store board_catalog in Sphinx domain"
  • zephyrproject-rtos/zephyr@42354cc
  • zephyrproject-rtos/zephyr@15f0894
  • zephyrproject-rtos/zephyr@15f0894
  • zephyrproject-rtos/zephyr@04e6406
  • zephyrproject-rtos/zephyr@239f430
  • zephyrproject-rtos/zephyr@86b72ee
  • zephyrproject-rtos/zephyr@c552930
  • zephyrproject-rtos/zephyr@a5ecd33
  • zephyrproject-rtos/zephyr@f2f1496 (!) "doc: Introduce boards catalog"
  • zephyrproject-rtos/zephyr@c487259
  • zephyrproject-rtos/zephyr@793c70d
  • zephyrproject-rtos/zephyr@3d7bb30
• doc: get output folder from environment zephyrproject-rtos/zephyr#78870 – Renames environment variable DOCS_HTML_DIR to OUTPUT_DIR. See:
  • zephyrproject-rtos/zephyr@fd58374
• doc: add make html-live and html-live-fast zephyrproject-rtos/zephyr#72607 – Control Sphinx output folder from CMake with environment variable DOCS_HTML_DIR. See:
  • zephyrproject-rtos/zephyr@2e99de8
• doc: add Doxygen preview tooltips to C symbols zephyrproject-rtos/zephyr#77093 – See:
  • zephyrproject-rtos/zephyr@bd29c5c

To Reproduce
Steps to reproduce the behavior:

1. proper Bridle workspace setup from main branch
2. cmake -Bbuild/bridle-doc -GNinja bridle/doc
3. ninja -Cbuild/bridle-doc zephyr-doxygen
4. ninja -Cbuild/bridle-doc bridle-doxygen
5. ninja -Cbuild/bridle-doc build-all
6. See error:

   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.

• 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