From 57a92e985f04ee2450aedd87409da5bbb86c5448 Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Wed, 16 Sep 2026 10:20:50 +0000 Subject: [PATCH 1/3] Exclude baselibs' cpp-style-guide.md from aggregated docs instead of adding it to toctree Baselibs deliberately excludes docs/cpp-style-guide.md from its own Sphinx build (see its docs/conf.py exclude_patterns), likely because it's an internal/AI-agent style guide rather than public docs. Patch 006-include-cpp-style-guide-in-toctree.patch worked around the resulting 'document not in any toctree' warning in reference_integration's aggregated docs build by linking it into baselibs' docs/index.rst - which made it visible in reference_integration even though it isn't in baselibs' own docs. Since reference_integration's docs build uses a single top-level docs/conf.py (source_dir = 'docs' in the docs() call) rather than each module's own conf.py, exclude_patterns must be set there to have any effect on the aggregated tree. Add an entry scoped to baselibs' mount path (modules/score_baselibs/cpp-style-guide.md, see bazel_common/docs_bundles.bzl) so the file is excluded consistently in both baselibs' own docs and reference_integration's aggregated docs, and drop the now-unneeded patch. --- .../score_modules_target_sw.MODULE.bazel | 1 - docs/conf.py | 6 ++++++ known_good.json | 3 +-- ...6-include-cpp-style-guide-in-toctree.patch | 20 ------------------- 4 files changed, 7 insertions(+), 23 deletions(-) delete mode 100644 patches/baselibs/006-include-cpp-style-guide-in-toctree.patch diff --git a/bazel_common/score_modules_target_sw.MODULE.bazel b/bazel_common/score_modules_target_sw.MODULE.bazel index 52ba2aa699a..a663bfbbd61 100644 --- a/bazel_common/score_modules_target_sw.MODULE.bazel +++ b/bazel_common/score_modules_target_sw.MODULE.bazel @@ -23,7 +23,6 @@ git_override( "//patches/baselibs:001-restore-trace-library-mock-visibility.patch", "//patches/baselibs:002-restore-qnx8-poll-workaround.patch", "//patches/baselibs:005-rename-manual-verification-report-id.patch", - "//patches/baselibs:006-include-cpp-style-guide-in-toctree.patch", ], remote = "https://github.com/eclipse-score/baselibs.git", ) diff --git a/docs/conf.py b/docs/conf.py index a1c839df8bd..afe3e6616b4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,6 +57,12 @@ def _patch_needpie_suppress_legend() -> None: "bazel-*", ".venv*", "_build", + # Baselibs deliberately excludes this from its own docs build (see its + # docs/conf.py); keep it excluded here too instead of surfacing it only + # in the aggregated reference_integration docs. Scoped to baselibs' mount + # point (see bazel_common/docs_bundles.bzl) so it doesn't accidentally + # hide a same-named file another module might add later. + "modules/score_baselibs/cpp-style-guide.md", ] # Enable markdown rendering diff --git a/known_good.json b/known_good.json index 8024415c01a..4491f763702 100644 --- a/known_good.json +++ b/known_good.json @@ -6,8 +6,7 @@ "bazel_patches": [ "//patches/baselibs:001-restore-trace-library-mock-visibility.patch", "//patches/baselibs:002-restore-qnx8-poll-workaround.patch", - "//patches/baselibs:005-rename-manual-verification-report-id.patch", - "//patches/baselibs:006-include-cpp-style-guide-in-toctree.patch" + "//patches/baselibs:005-rename-manual-verification-report-id.patch" ], "metadata": { "code_root_path": "//score/...", diff --git a/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch b/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch deleted file mode 100644 index bc916546678..00000000000 --- a/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch +++ /dev/null @@ -1,20 +0,0 @@ -diff --git a/docs/index.rst b/docs/index.rst -index c2f4a6ef1..c4b8a57c1 100644 ---- a/docs/index.rst -+++ b/docs/index.rst -@@ -56,6 +56,15 @@ The Components documentation provides detailed documentation for each individual - baselibs/components/index - - -+Development Guidelines -+----------------------- -+ -+.. toctree:: -+ :maxdepth: 1 -+ -+ cpp-style-guide -+ -+ - Quick Start - Building and Testing - ---------------------------------- - From 412212f0396aee130da83a3c74bf55b9701d9761 Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Wed, 16 Sep 2026 10:54:03 +0000 Subject: [PATCH 2/3] Revert: restore cpp-style-guide toctree patch The previous commit tried to fix the "document isn't included in any toctree" warning by adding an exclude_patterns entry to reference_integration's docs/conf.py instead of linking the file into a toctree. That does not work: baselibs' docs/ is pulled in via the sphinx_mounts extension (score_mounts), which walks each mounted directory itself using the ignore crate and injects absolute source paths directly into Sphinx's Project. It never goes through the host srcdir's normal file discovery, so Sphinx's exclude_patterns (which only applies to files discovered under the configured srcdir) has no effect on mounted files. sphinx_mounts does support per-mount include/exclude overrides, but that option is not currently plumbed through by score_docs_as_code's Bazel bundling macros (DocsBundleInfo / mounts manifest), so it cannot be set from reference_integration today. Restore the original, working fix: link cpp-style-guide into baselibs' own docs/index.rst toctree via the patch, and re-add it to known_good.json's bazel_patches list. --- .../score_modules_target_sw.MODULE.bazel | 1 + docs/conf.py | 6 ------ known_good.json | 3 ++- ...6-include-cpp-style-guide-in-toctree.patch | 20 +++++++++++++++++++ 4 files changed, 23 insertions(+), 7 deletions(-) create mode 100644 patches/baselibs/006-include-cpp-style-guide-in-toctree.patch diff --git a/bazel_common/score_modules_target_sw.MODULE.bazel b/bazel_common/score_modules_target_sw.MODULE.bazel index a663bfbbd61..52ba2aa699a 100644 --- a/bazel_common/score_modules_target_sw.MODULE.bazel +++ b/bazel_common/score_modules_target_sw.MODULE.bazel @@ -23,6 +23,7 @@ git_override( "//patches/baselibs:001-restore-trace-library-mock-visibility.patch", "//patches/baselibs:002-restore-qnx8-poll-workaround.patch", "//patches/baselibs:005-rename-manual-verification-report-id.patch", + "//patches/baselibs:006-include-cpp-style-guide-in-toctree.patch", ], remote = "https://github.com/eclipse-score/baselibs.git", ) diff --git a/docs/conf.py b/docs/conf.py index afe3e6616b4..a1c839df8bd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -57,12 +57,6 @@ def _patch_needpie_suppress_legend() -> None: "bazel-*", ".venv*", "_build", - # Baselibs deliberately excludes this from its own docs build (see its - # docs/conf.py); keep it excluded here too instead of surfacing it only - # in the aggregated reference_integration docs. Scoped to baselibs' mount - # point (see bazel_common/docs_bundles.bzl) so it doesn't accidentally - # hide a same-named file another module might add later. - "modules/score_baselibs/cpp-style-guide.md", ] # Enable markdown rendering diff --git a/known_good.json b/known_good.json index 4491f763702..8024415c01a 100644 --- a/known_good.json +++ b/known_good.json @@ -6,7 +6,8 @@ "bazel_patches": [ "//patches/baselibs:001-restore-trace-library-mock-visibility.patch", "//patches/baselibs:002-restore-qnx8-poll-workaround.patch", - "//patches/baselibs:005-rename-manual-verification-report-id.patch" + "//patches/baselibs:005-rename-manual-verification-report-id.patch", + "//patches/baselibs:006-include-cpp-style-guide-in-toctree.patch" ], "metadata": { "code_root_path": "//score/...", diff --git a/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch b/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch new file mode 100644 index 00000000000..bc916546678 --- /dev/null +++ b/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch @@ -0,0 +1,20 @@ +diff --git a/docs/index.rst b/docs/index.rst +index c2f4a6ef1..c4b8a57c1 100644 +--- a/docs/index.rst ++++ b/docs/index.rst +@@ -56,6 +56,15 @@ The Components documentation provides detailed documentation for each individual + baselibs/components/index + + ++Development Guidelines ++----------------------- ++ ++.. toctree:: ++ :maxdepth: 1 ++ ++ cpp-style-guide ++ ++ + Quick Start - Building and Testing + ---------------------------------- + From 91e750c6d45ebb1bec28093220edef04dd1458e1 Mon Sep 17 00:00:00 2001 From: Anton Krivoborodov Date: Wed, 16 Sep 2026 11:06:41 +0000 Subject: [PATCH 3/3] Exclude baselibs' cpp-style-guide.md via docs/.ignore instead of a toctree link Root cause of the earlier attempt's failure: reference_integration's docs build does not merge bundled modules into a single Sphinx source tree. Each module's docs/ bundle is attached via the sphinx_mounts extension (score_mounts), which walks the mounted directory itself (using the "ignore" Rust crate) and injects absolute source paths directly into Sphinx's Project, bypassing the host project's normal file discovery entirely. Sphinx's own exclude_patterns (docs/conf.py) only applies to files discovered under the configured srcdir, so it has no effect on files pulled in through a mount - confirmed by CI run 35085273728, which still reported cpp-style-guide.md as "document isn't included in any toctree" after adding it to exclude_patterns. sphinx_mounts does honour per-directory .ignore/.gitignore files inside each mounted tree (gitignore=True by default), the same as any Rust "ignore"-crate-based tool (e.g. ripgrep). Add docs/.ignore to baselibs via a patch, listing cpp-style-guide.md, so sphinx_mounts's own walker skips the file - consistent with baselibs' own docs/conf.py, which already excludes it from baselibs' native docs build. This makes the file invisible in both baselibs' own docs and reference_integration's aggregated docs, without needing any change to reference_integration's docs/conf.py or to the external score_docs_as_code tooling. Verified locally: `bazel run //:docs_shim -- --github_user=eclipse-score --github_repo=reference_integration` completes with "build succeeded." and no toc.not_included warning for cpp-style-guide.md. Supersedes 006-include-cpp-style-guide-in-toctree.patch, which linked the file into baselibs' docs/index.rst toctree purely to silence the same warning - that made the file visible in reference_integration even though baselibs itself deliberately excludes it. --- .../score_modules_target_sw.MODULE.bazel | 2 +- known_good.json | 2 +- ...lude-cpp-style-guide-from-docs-mount.patch | 12 +++++++++++ ...6-include-cpp-style-guide-in-toctree.patch | 20 ------------------- 4 files changed, 14 insertions(+), 22 deletions(-) create mode 100644 patches/baselibs/006-exclude-cpp-style-guide-from-docs-mount.patch delete mode 100644 patches/baselibs/006-include-cpp-style-guide-in-toctree.patch diff --git a/bazel_common/score_modules_target_sw.MODULE.bazel b/bazel_common/score_modules_target_sw.MODULE.bazel index 52ba2aa699a..dce21aaa15c 100644 --- a/bazel_common/score_modules_target_sw.MODULE.bazel +++ b/bazel_common/score_modules_target_sw.MODULE.bazel @@ -23,7 +23,7 @@ git_override( "//patches/baselibs:001-restore-trace-library-mock-visibility.patch", "//patches/baselibs:002-restore-qnx8-poll-workaround.patch", "//patches/baselibs:005-rename-manual-verification-report-id.patch", - "//patches/baselibs:006-include-cpp-style-guide-in-toctree.patch", + "//patches/baselibs:006-exclude-cpp-style-guide-from-docs-mount.patch", ], remote = "https://github.com/eclipse-score/baselibs.git", ) diff --git a/known_good.json b/known_good.json index 8024415c01a..340d806d2fb 100644 --- a/known_good.json +++ b/known_good.json @@ -7,7 +7,7 @@ "//patches/baselibs:001-restore-trace-library-mock-visibility.patch", "//patches/baselibs:002-restore-qnx8-poll-workaround.patch", "//patches/baselibs:005-rename-manual-verification-report-id.patch", - "//patches/baselibs:006-include-cpp-style-guide-in-toctree.patch" + "//patches/baselibs:006-exclude-cpp-style-guide-from-docs-mount.patch" ], "metadata": { "code_root_path": "//score/...", diff --git a/patches/baselibs/006-exclude-cpp-style-guide-from-docs-mount.patch b/patches/baselibs/006-exclude-cpp-style-guide-from-docs-mount.patch new file mode 100644 index 00000000000..bc3ff1019bd --- /dev/null +++ b/patches/baselibs/006-exclude-cpp-style-guide-from-docs-mount.patch @@ -0,0 +1,12 @@ +diff --git a/docs/.ignore b/docs/.ignore +new file mode 100644 +--- /dev/null ++++ b/docs/.ignore +@@ -0,0 +1,7 @@ ++# reference_integration mounts this directory into its aggregated docs ++# build via sphinx_mounts, which walks it independently of Sphinx's own ++# exclude_patterns. baselibs' own docs/conf.py already excludes this file ++# from baselibs' native docs build; mirror that here so it stays excluded ++# from the aggregated build too, instead of only being reachable through a ++# toctree link added solely for reference_integration's benefit. ++cpp-style-guide.md diff --git a/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch b/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch deleted file mode 100644 index bc916546678..00000000000 --- a/patches/baselibs/006-include-cpp-style-guide-in-toctree.patch +++ /dev/null @@ -1,20 +0,0 @@ -diff --git a/docs/index.rst b/docs/index.rst -index c2f4a6ef1..c4b8a57c1 100644 ---- a/docs/index.rst -+++ b/docs/index.rst -@@ -56,6 +56,15 @@ The Components documentation provides detailed documentation for each individual - baselibs/components/index - - -+Development Guidelines -+----------------------- -+ -+.. toctree:: -+ :maxdepth: 1 -+ -+ cpp-style-guide -+ -+ - Quick Start - Building and Testing - ---------------------------------- -