[Docs Rendering] fix several bugs - #471
Merged
Merged
Conversation
hoe-jo
commented
Sep 17, 2026
hoe-jo
commented
Contributor
- architectural_design: per-view navigation
- add --output-stem to name outputs independent of input path
- architectural_design: share ARCH_VIEWS, narrow view_root_indexes, cleanup
- dependable_element: unconditional label prefixing, view refs as dict, staged-path collision tests
- fix docs failures
- puml_utils.bzl: rewrite make_puml_rst_navigation to emit one directory- structured index.rst tree per view (mirroring source layout) - architectural_design.bzl: loop over the four views (static/dynamic/ public_api/internal_api) generically Colocate every view file (not just puml) preserving relative directory structure. Redesign the returned SphinxSourcesInfo so srcs holds only each view's root index - providers.bzl: replace the four separate *_doc_files fields on ArchitecturalDesignInfo with a single view_indexes dict (view name -> navigation struct or None) reflecting the generic per-view design.
Every write_*_to_file helper (FlatBuffers, lobster, idmap) derives its output filename from the passed-in input path's file stem alone. Add --output-stem <STEM> so a caller that needs a specific, disambiguated output filename (e.g. a Bazel rule staging same-named diagrams from different packages) can request it directly, instead of having to stage the actual input file under a symlink named after the desired stem.
…anup - Extract the static/dynamic/public_api/internal_api view list into a new shared bazel/rules/rules_score/private/views.bzl - Narrow ArchitecturalDesignInfo.view_indexes (Dict[str, NavigationStruct]) to view_root_indexes (Dict[str, File|None]) - _colocate_view_files now returns Dict[str, File] keyed by relative path instead of a positionally-matched List[File]; emit_view_navigation takes that dict directly instead of rebuilding it internally from a zipped list. - relative_source_path reads file.owner directly instead of getattr(file, "owner", None) -- test fakes always set it. - Collapse the redundant view_fbs/view_fbs_files dicts in architectural_design.bzl into one. - Trim the architectural_design() macro's docstring, pointing to docs/user_guide/architectural_design.rst instead of duplicating its authoring-mode prose. - Replace the bespoke puml_layout_crash_repro_test.bzl analysistest rule with skylib's build_test for the two "does it build" regression fixtures. - Add a diagram-free view regression test (authored_layout_diagram_free_test): a view with only a hand-authored index.md and no diagrams at all must still stage a valid root index (authored body composed above an empty toctree). - Add stem_collision_fails_test: an expect_failure analysistest covering _disambiguated_stems' residual-collision fail() path (two files whose basenames collide and whose directory-disambiguated stems collide too).
… staged-path collision tests - _process_artifact_type: removed the use_label_subdirectories = len(attr_list) > 1 conditional. Every label attached to an artifact-type attribute (assumptions_of_use, dependability_analysis, checklists, glossary) now gets an unconditional "<target_name>/" staging prefix - Applied the same unconditional "<target_name>/" prefix to the feature_requirements and assumed_system_requirements loops (previously staged with no prefix at all, regardless of how many requirements targets were attached). - _process_architectural_design_files: collapsed its 6-tuple return (output_files, static_refs, dynamic_refs, public_api_refs, internal_api_refs, unclassified_refs) to (output_files, refs_by_view, unclassified_refs), with refs_by_view keyed generically over ARCH_VIEWS. - Fixed a latent bug in _check_staged_path's callers: a detected collision was only recorded in `errors` for a later fail(), but the colliding file's declare_file()/symlink() actions were still unconditionally registered -- so two genuinely different source files staging to the same path tripped Bazel's own ActionConflictException before this rule's fail() was ever reached - Added 2 regression tests - Extracted test/lib/find_runfile.sh
…ctions - examples/seooc/design/BUILD, index.md: the "standalone page" example file arch_design.rst no longer exists in this exampl - docs/user_guide/architectural_design.rst: fixed the "working demonstration of all three modes"
hoe-jo
requested review from
LittleHuba,
castler,
limdor and
ramceb
as code owners
September 17, 2026 08:55
Coverage ReportCoverage report was generated. Full report can be downloaded from the CI artifacts (expand Artifacts at the bottom of the run). Overall coverage rate: |
LittleHuba
approved these changes
Sep 17, 2026
LittleHuba
left a comment
LittleHuba
left a comment
Contributor
There was a problem hiding this comment.
Finding is no blocker IMHO. Potentially relevant for a follow-up. @hoe-jo let's talk about this.
Comment on lines
+166
to
+170
| - Directory levels that hold nothing of their own and lead to a single | ||
| subdirectory are skipped, so a diagram at ``foo/bar/baz.puml`` is reached | ||
| through one ``foo/bar/index.rst`` rather than a chain of navigation pages | ||
| that each contain a single link. A view consisting of one page and nothing | ||
| else gets no generated index at all; that page becomes the view's root. |
Contributor
There was a problem hiding this comment.
That could be weird when you slowly migrate to rules_score.
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.