[Docs Rendering] fix several bugs

.github/skills/score-architecture/SKILL.md

@@ -330,9 +330,9 @@ One target bundles every diagram kind (from [`examples/seooc/design/BUILD`](../.
 ```starlark
 architectural_design(
     name         = "sample_seooc_design",
-    static       = ["static_design.puml", "arch_design.rst"],
+    static       = ["static_design.puml", "index.md"],
     dynamic      = ["dynamic_design.puml"],
-    public_api   = ["public_api.puml"],
+    public_api   = ["public_api.puml", "public_api.rst"],
     internal_api = ["internal_api.puml"],
     visibility   = ["//visibility:public"],
     # maturity = "development",  # write validation findings without failing the build
@@ -341,8 +341,30 @@ architectural_design(
 
 `static`/`dynamic` accept `.puml`, `.plantuml`, `.png`, `.svg`, `.rst`, `.md`. To combine a
 diagram with prose, add both the RST/Markdown wrapper *and* the referenced `.puml` to the same
-list (as `static_design.puml` + `arch_design.rst` above); the wrapper embeds the diagram with
-`.. uml:: file.puml`.
+list (as `public_api.puml` + `public_api.rst` above, which overrides `public_api.puml`'s
+generated wrapper page); the wrapper embeds the diagram with `.. uml:: file.puml`. `index.md`
+above is a directory-level `index` page instead, so it *composes* with (rather than overrides)
+the static view's generated navigation — see the next paragraph.
+
+Each view builds a navigation tree mirroring the on-disk directory layout of its diagrams:
+every `.puml` gets an auto-generated wrapper page, and every directory gets a generated
+`index.rst` listing its diagrams and sub-directories. Authored pages slot into that tree
+**by name**:
+
+- **`<stem>.rst`/`<stem>.md` next to `<stem>.puml` overrides** that diagram's generated
+  wrapper page — this is exactly the wrapper pattern above. The `.puml` is still staged
+  beside it so `.. uml:: <stem>.puml` resolves.
+- **`index.rst`/`index.md` in a directory composes** with that directory's generated
+  navigation: the authored body renders first, the generated toctree follows. It never
+  replaces it, because a missing toctree entry means an orphaned page. **Give the authored
+  body a section title** — it becomes the page title, and without one Sphinx warns that a
+  toctree entry has no title.
+
+Build-time errors (each naming the offending files): a diagram named `index.puml`/
+`index.plantuml` (that stem is reserved for the navigation page); two files in one view
+resolving to the same staged path; a stem having both `.rst` and `.md`, or both `.puml` and
+`.plantuml`. For a page you want fully outside this scheme, leave the `.puml` out of the view
+attribute and reference it via your own `.. uml::` elsewhere in the docs tree.
 
 ### `unit_design`
 

bazel/rules/rules_score/docs/integration_guide.rst

@@ -258,6 +258,26 @@ Design Rationale
 
 Reference implementation: `examples/seooc <https://github.com/eclipse-score/score-tooling/tree/main/bazel/rules/rules_score/examples/seooc>`_ in the score-tooling repository.
 
+Staged Layout of ``architectural_design`` Output
+--------------------------------------------------
+
+A ``dependable_element`` stages each of its ``architectural_design`` dependencies
+under that dependency's **target name**:
+
+.. code-block:: text
+
+   architectural_design/<architectural_design target name>/<view>/...
+
+This shape does not depend on how many ``architectural_design`` labels are
+attached, so published HTML URLs stay stable as the element grows. The same
+``<target name>/`` prefix is applied to every other artifact-type attribute
+(``assumptions_of_use``, ``dependability_analysis``, ``checklists``,
+``glossary``, and the requirements attributes).
+
+If two ``architectural_design`` labels from different packages share a target
+name, or if two files within one label resolve to the same relative path, the
+build fails with an error.
+
 ---
 
 .. _sphinx-hermetic-tool-setup:

bazel/rules/rules_score/docs/user_guide/architectural_design.rst

@@ -147,6 +147,77 @@ Common anti-patterns
 - **Leaky public API** — exposing an interface publicly for convenience. It then
   drags in unnecessary failure modes and AoUs.
 
+Rendering: Diagrams, Wrapper Pages, and Directory Navigation
+---------------------------------------------------------------
+
+Each view (``static``, ``dynamic``, ``public_api``, ``internal_api``) is just a
+flat list of ``.puml``/``.plantuml`` files, but Sphinx needs an actual page to
+put every diagram on, plus a place in the sidebar to reach it from.
+``architectural_design`` builds that structure automatically:
+
+- Every diagram gets an auto-generated wrapper page — a ``.rst`` file
+  containing a single ``.. uml::`` directive — named after the diagram's own
+  file stem (``foo.puml`` → page ``foo``).
+- Every directory that contains at least one diagram or authored page gets a
+  generated ``index.rst`` with a ``toctree`` listing that directory's pages
+  and its subdirectories, mirroring the on-disk layout of the files you passed
+  to ``static``/``dynamic``/``public_api``/``internal_api``. Nesting is
+  unlimited.
+- 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.
+- The view's top-level (root) index is the single toctree entry surfaced on
+  the enclosing ``dependable_element`` page for that view.
+
+Authoring pages alongside diagrams
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A generated wrapper page is only a placeholder; real prose belongs alongside
+your ``.puml`` files, passed in the same view attribute. What happens depends
+on the file's stem relative to the diagrams already in that directory:
+
+.. list-table::
+   :header-rows: 1
+
+   * - You add
+     - Effect
+     - When to use it
+   * - ``<stem>.rst``/``.md`` with no matching ``<stem>.puml`` in the same
+       directory
+     - **Standalone page** — an ordinary extra entry in that directory's
+       toctree.
+     - Prose that isn't about one specific diagram — design rationale, an
+       overview, background context.
+   * - ``<stem>.rst``/``.md`` next to a same-stem ``<stem>.puml``/
+       ``.plantuml``
+     - **Override** — replaces that diagram's generated wrapper page
+       outright. The ``.puml`` is still staged as a sibling, so your page can
+       embed it with its own ``.. uml:: <stem>.puml``.
+     - You want narrative directly around one specific diagram instead of it
+       rendering bare.
+   * - ``index.rst``/``index.md``
+     - **Compose** — your content is rendered *above* the generated
+       directory-level toctree, which is otherwise left untouched (every
+       diagram in that directory keeps its navigation entry). Your title
+       becomes the index page's title.
+     - A directory-level introduction that must not hide any diagram from
+       the navigation.
+
+A ``.puml``/``.plantuml`` file whose own stem is literally ``index`` is
+rejected at analysis time — that stem is reserved for the directory's
+generated navigation page; name the diagram something else.
+
+Two files that would stage at the same relative path (for example both a
+``.rst`` and a ``.md`` for the same stem) also fail the build, with a message
+naming both conflicting sources, instead of surfacing a raw Bazel
+action-conflict error.
+
+See ``examples/seooc/design`` for a working demonstration: ``index.md``
+composes an introduction above the static view's root navigation, and
+``public_api.rst`` overrides the generated wrapper for ``public_api.puml``.
+
 Static Architecture
 --------------------
 

bazel/rules/rules_score/examples/seooc/design/BUILD

@@ -26,10 +26,11 @@ architectural_design(
     ],
     public_api = [
         "public_api.puml",
+        "public_api.rst",
     ],
     static = [
         "static_design.puml",
-        "arch_design.rst",
+        "index.md",
     ],
     visibility = ["//visibility:public"],
 )

bazel/rules/rules_score/examples/seooc/design/index.md

@@ -0,0 +1,19 @@
+<!-- ----------------------------------------------------------------------------
+  Copyright (c) 2025 Contributors to the Eclipse Foundation
+
+  See the NOTICE file(s) distributed with this work for additional
+  information regarding copyright ownership.
+
+  This program and the accompanying materials are made available under the
+  terms of the Apache License Version 2.0 which is available at
+  https://www.apache.org/licenses/LICENSE-2.0
+
+  SPDX-License-Identifier: Apache-2.0
+----------------------------------------------------------------------------- -->
+
+# Safety Software SEooC Example — Static Design
+
+This is a **compose** example (see `architectural_design.rst`'s "Authoring
+Pages Alongside Diagrams"): this file is named `index.md`, so its content is
+rendered above the generated navigation for this directory instead of
+replacing it — `static_design` below keeps its own entry.

bazel/rules/rules_score/examples/seooc/design/arch_design.rst → bazel/rules/rules_score/examples/seooc/design/public_api.rst

@@ -12,27 +12,18 @@
    # SPDX-License-Identifier: Apache-2.0
    # *******************************************************************************
 
-Architectural Design
-====================
-
-This is the architectural design of the Safety Software SEooC Example:
-
-The :term:`Architectural Design` describes how each :term:`Component`
-contributes to fulfilling :term:`Feature Requirements` under the selected
-:term:`Integrity Level`.
-
-Static Architecture
--------------------
+Public API
+==========
 
-.. uml:: static_design.puml
-   :align: center
-   :alt: Static Component Architectural Design
-   :width: 100%
+This is an **override** example (see ``architectural_design.rst``'s
+"Authoring Pages Alongside Diagrams"): this file shares its stem with
+``public_api.puml``, so it replaces that diagram's generated wrapper page
+outright. The diagram is still staged as a sibling, so it can be embedded
+here directly.
 
-Public API
-----------
+The SEooC exposes exactly one operation, ``GetNumber()``, on
+``SampleLibraryAPI``.
 
 .. uml:: public_api.puml
    :align: center
-   :alt: Public API of the SEooC Example
-   :width: 100%
+   :alt: SEooC example public API