Conversation
…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.
antonkri
requested review from
AlexanderLanin,
FScholPer,
MaximilianSoerenPollak,
PiotrKorkus,
dcalavrezo-qorix,
lurtz,
nradakovic,
opajonk and
pawelrutkaq
as code owners
September 16, 2026 10:29
PiotrKorkus
previously approved these changes
Sep 16, 2026
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.
…ctree 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.
PiotrKorkus
reviewed
Sep 16, 2026
Contributor
There was a problem hiding this comment.
if baselibs is also excluding this file from their docs build and previous exclude_pattern approach was not working here in ref_int - should this ignore file be located in baselibs itself and we wont need to do the patch here?
I assume both solutions have exactly the same outcome or?
Contributor
Author
There was a problem hiding this comment.
Hey @PiotrKorkus ,
I've checked it once again, I guess, with the new approach the file/page is away. Baselibs ignore this file in conf.py. Putting the same in the ref_int will not work because of the bundles approach (that's what copilot says).
|
The created documentation from the pull request is available at: docu-html |
PiotrKorkus
requested changes
Sep 16, 2026
PiotrKorkus
left a comment
PiotrKorkus
left a comment
Contributor
There was a problem hiding this comment.
the page is in rendered documentation, it was not ignored
https://eclipse-score.github.io/reference_integration/pr-347/modules/score_baselibs/cpp-style-guide.html
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.