feat: support toctree_index parameter

[a-zw]

📌 Description

Sphinx-mount provides a toctree_index parameter but our wrapper did not provide it yet.

🚨 Impact Analysis

• This change does not violate any tool requirements and is covered by existing tool requirements
• This change does not violate any design decisions
• Otherwise I have created a ticket for new tool qualification

✅ Checklist

• Added/updated documentation for new or changed features
• Added/updated tests to cover the changes
• Followed project coding standards and guidelines

[Copilot]

Copilot review overview

🟡 Changes recommended

Moderate issues remain in TOML round-tripping and negative-index validation; file-list coverage and contract documentation also need updates.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2 · 1

Open (3)

• Serialize non-default toctree_index to generated TOML · New
• Reject negative toctree_index values in JSON loader · New
• Test toctree_index for explicit file-list bundles · New

What changed in this PR

Adds toctree_index support across Bazel bundle composition, manifests, runtime mounting, tests, and documentation.

Changes:

• Propagates and validates the placement index.
• Updates nested-bundle fixtures and expected outputs.
• Documents the new configuration option.

File	Summary
src/​tests/​docs_bzl/​scenarios/​nested_bundles/​host_docs/​concepts/​index.rst	Adds a second target toctree.
src/​tests/​docs_bzl/​scenarios/​nested_bundles/​BUILD	Configures index 1.
src/​tests/​docs_bzl/​scenarios/​nested_bundles/​_expected/​ordered_aggregate_manifest.json	Updates aggregate metadata.
src/​tests/​docs_bzl/​scenarios/​nested_bundles/​_expected/​mounts_manifest.json	Updates mount metadata.
src/​tests/​docs_bzl/​scenarios/​nested_bundles/​_expected/​docs/​concepts/​index.html	Updates rendered placement.
src/​tests/​docs_bzl/​scenarios/​nested_bundles/​_expected/​docs/​concepts/​example_bundle/​child/​landing.html	Updates navigation output.
src/​extensions/​score_mounts/​tests/​test_resolver.py	Tests parsing and defaults.
src/​extensions/​score_mounts/​_resolver.py	Parses the new manifest field. Moderate: reject negative indices (3 votes).
src/​extensions/​score_mounts/​__init__.py	Passes the index to runtime mounts. Moderate: preserve non-default indices in TOML serialization (3 votes); Nit: cover the file-list path (2 votes).
docs/​reference/​bazel_macros.rst	Documents the macro parameter.
docs/​how-to/​bundles/​index.rst	Documents placement semantics.
docs/​concepts/​mounts/​index.rst	Documents mount behavior. Nit: update the maintainer-facing manifest contract (1 vote).
bzl/​mount_rules.bzl	Emits index metadata in manifests.
bzl/​bundle_rules.bzl	Propagates and validates bundle placement indices.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

Documentation preview for this pull request is available at:
pr-844: https://eclipse-score.github.io/docs-as-code/pr-844/

[AlexanderLanin]

See AI feedback, otherwise LGTM, lets merge this after #841

[AlexanderLanin]

New PR overview attempt: Please mark the PR as ready for review once conflicts are resolved

[AlexanderLanin]

@copilot merge latest main branch in here. mark the PR as ready for review once done.

[Copilot]

@copilot merge latest main branch in here. mark the PR as ready for review once done.

Merged main into this branch in b18e53c and pushed the follow-up conflict-resolution fixes through bb70cc3. I can’t mark the PR ready for review with the tools available in this session.

[Copilot]

Copilot review overview

🟡 Changes recommended

Generated TOML drops the new setting, while manifest validation and expected output still contain correctness gaps.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 4 · 1

Open (6)

• Initialize toctree_index on the root manifest entry · New
• Reject negative toctree indices in the runtime loader · New
• Require the manifest's mounts collection · New
• Reject negative toctree_index values in JSON loader
• Serialize non-default toctree_index to generated TOML
• Test toctree_index for explicit file-list bundles

[Copilot]

Copilot review overview

🔵 Needs a closer look

Generated ubproject.toml files currently discard toctree_index, causing downstream consumers to use the wrong toctree.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Serialize non-default toctree_index to generated TOML
• Test toctree_index for explicit file-list bundles

Resolved since last review (4)

• Initialize toctree_index on the root manifest entry
• Require the manifest's mounts collection
• Reject negative toctree indices in the runtime loader
• Reject negative toctree_index values in JSON loader