docs: add Sphinx documentation site with Bazel

[clanghans]

Summary

• Adds a `score_docs_as_code`-based Sphinx documentation site covering
  how-to guides, Bazel macro reference, plugin reference, and architecture
  concepts
• Follows the S-CORE module folder structure
  with stub sections for manual, release notes, safety, security, and
  verification report
• Wires in a CI workflow for docs verification and GitHub Pages deployment
• Makes `itf.yml` reusable (`workflow_call:`) for future dependency from
  the docs pipeline

What's included

Infrastructure

• `MODULE.bazel`: adds `score_docs_as_code` dep (v4.0.1)
• `.bazelrc`: adds Java 17 config required by PlantUML
• `BUILD`: adds `docs()` macro target
• `.gitignore`: ignores `_build/` and auto-generated `docs/ubproject.toml`

Documentation (`docs/`)

• `conf.py` — minimal Sphinx config loading `score_sphinx_bundle`
• `index.rst` — landing page with 3-column how-to / reference / concepts grid
• `how-to/get_started.md` — from-scratch setup: `bazel_dep`, `.bazelrc`,
  `git_override`, first test, `@score_itf` load prefix note, attribute plugin
  example for requirement traceability
• `how-to/write_tests.md` — Docker (`target.execute()` vs `target.ssh()`),
  QEMU, capability-based tests, `--keep-target`
• `how-to/plugins.md` — built-in plugins, custom plugin creation
• `reference/bazel_macros.rst` — table-based `py_itf_test` and
  `py_itf_plugin` attribute reference
• `reference/plugins.rst` — capabilities table, exhaustive CLI args per plugin
• `concepts/architecture.rst` — target abstraction, capability system,
  plugin lifecycle, Bazel integration; includes PlantUML component diagram
• `concepts/itf_architecture.puml` — architecture diagram using
  `!pragma layout smetana` (no Graphviz dependency)
• `manual/index.rst` — stub: integration and safety manual
• `release/index.rst` — stub: per-version release notes
• `safety_mgt/index.rst` — stub: safety plan and package
• `security_mgt/index.rst` — stub: security plan, package, and SBOM
• `verification_report/index.rst` — stub: verification report and safety
  analysis reviews

CI

• `.github/workflows/docs.yml` — verify + build/deploy to GitHub Pages on
  PR and push to main
• `.github/workflows/itf.yml` — adds `workflow_call:` trigger

Test plan

• `bazel run //:docs` builds cleanly with no warnings
• All 15 source pages render including the PlantUML diagram (SVG)
• PlantUML uses Smetana layout — no Graphviz dependency, works in CI
• CI docs-verify passes on this PR
• GitHub Pages deploys on merge to main

Notes

• The `unit-tests` job in `docs.yml` is commented out. When the ITF unit
  test suite is ready to run in CI, uncomment it and add it to
  `docs-build.needs`.
• `git_override` example in `get_started.md` points to the current
  `origin/main` HEAD for users who need unreleased fixes.
• Stub sections (`manual`, `release`, `safety_mgt`, `security_mgt`,
  `verification_report`) contain only a `.. note::` placeholder listing
  planned content. They establish the folder structure now to avoid a
  separate restructuring PR later.

[Copilot]

Pull request overview

Adds a Bazel-built Sphinx documentation site for ITF (how-to, reference, concepts) and wires CI to verify/build and publish docs via GitHub Pages, while making the existing ITF workflow reusable for composition.

Changes:

• Introduces a new docs/ Sphinx site (how-to guides, Bazel macro/rule reference, plugin reference, architecture + PlantUML diagram).
• Adds a root //:docs Bazel target and the score_docs_as_code module dependency.
• Adds GitHub Actions workflows for docs verification/build + makes itf.yml callable via workflow_call.

Reviewed changes

Copilot reviewed 17 out of 18 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
docs/reference/plugins.rst	Adds plugin catalog, capability table, and per-plugin CLI argument reference.
docs/reference/index.rst	Adds Reference section index and toctree.
docs/reference/bazel_macros.rst	Documents py_itf_test and py_itf_plugin usage and attributes.
docs/index.rst	Adds landing page with grid navigation + sitemap toctree.
docs/how-to/write_tests.md	Adds Docker/QEMU/capability-based testing guide and examples.
docs/how-to/plugins.md	Adds plugin usage guide and custom plugin example.
docs/how-to/index.rst	Adds How-To section index and toctree.
docs/how-to/get_started.md	Adds from-scratch setup guide including Bazel module + first test.
docs/conf.py	Adds minimal Sphinx configuration using score_sphinx_bundle.
docs/concepts/itf_architecture.puml	Adds PlantUML architecture diagram source.
docs/concepts/index.rst	Adds Concepts section index and toctree.
docs/concepts/architecture.rst	Adds architecture narrative + embeds PlantUML diagram.
MODULE.bazel	Adds score_docs_as_code dependency.
BUILD	Adds docs() macro target for building the Sphinx site.
.gitignore	Ignores Sphinx build output and auto-generated config file.
.github/workflows/itf.yml	Adds workflow_call trigger for reusability.
.github/workflows/docs.yml	Adds docs verify + build/deploy workflow using reusable workflows.
.bazelrc	Sets Java 17 toolchain flags (to support PlantUML).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 18 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[clanghans]

This might be out of scope for now though may will reduce future work time. In 1.0 (and probably earlier too) module will need to follow the documentation structure found here

Might be better to adapt this earlier than later. I also know there is this PR which makes this the default in module_template but unsure if they are in unison as I didnt check yet.

Fixed it and matched the folder structure. Leaving stubs since there is nothing to document in some directories.

[MaximilianSoerenPollak]

This might be out of scope for now though may will reduce future work time. In 1.0 (and probably earlier too) module will need to follow the documentation structure found here
Might be better to adapt this earlier than later. I also know there is this PR which makes this the default in module_template but unsure if they are in unison as I didnt check yet.

Fixed it and matched the folder structure. Leaving stubs since there is nothing to document in some directories.

@PandaeDo can you have a look if this looks right as a first option?

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[PandaeDo]

@clanghans If you like I can give you an introduction into the processes. We have also templates available that can easily copied and filled out. I'm pretty sure that you can use all of your content. But as the module might not be the only place to document it I'm sure that we can find this also easily out to speed the step of archiving compliance a litte bit up.

[PandaeDo]

As discussed with @clanghans it's fine from the perspective of the process community to use it as a initial version and update afterwards according to the processes and templates

[AlexanderLanin]

I guess we've discussed the boilerplate at length now. @ltekieli can you have a look at the actual content?

[ltekieli]

Hey @clanghans, I took a look at the workflow security setup. The current docs.yml uses pull_request_target, which is risky because the reusable workflows from cicd-workflows check out the PR's head ref and then run bazel run on it. Under pull_request_target that code executes with a GITHUB_TOKEN that has contents: write, pages: write, and id-token: write — so a malicious fork PR could get arbitrary code execution with write access to the repo and Pages.

I'd suggest the following changes (same pattern we already use in itf-qnx.yml):

1. Replace pull_request_target with pull_request — this ensures fork PRs never get a write-scoped token.
2. Skip fork PRs on docs-verify using the same guard as itf-qnx.yml:

   if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository

3. Run docs-build only in merge queue / push to main / release — not on PRs at all. The verification step already catches docs issues during PR review; the full build + deploy only needs to happen after reviews are done:

   if: github.event_name != 'pull_request'

4. Tighten top-level permissions to contents: read — the broad write permissions are only needed by docs-build, which already declares them at job level.

This also removes the always() condition on docs-build since it no longer runs on PRs and the simple needs: [docs-verify] dependency is sufficient.

5. Remove the commented-out unit-tests block entirely. Leaving it in with secrets: inherit is a footgun — when someone uncomments it, itf.yml has no permissions: block, so it would inherit the caller's write permissions and all secrets while running untrusted code. Better to remove it now and add it back properly in a dedicated PR where the permissions can be set up correctly (at minimum itf.yml would need an explicit permissions: { contents: read } block, and secrets: inherit should be reconsidered).

[ltekieli]

A few additional findings from reviewing the documentation content against the source code:

Documentation accuracy

1. capabilities shown as a public attribute (docs/concepts/architecture.rst and docs/concepts/itf_architecture.puml)
   The Target class stores capabilities in a private field _capabilities with a public accessor get_capabilities(). The docs and PlantUML diagram show capabilities : Set[str] as a public attribute, which doesn't exist. The PUML should show get_capabilities() -> Set[str] instead, and the code example in architecture.rst around line 36 should use the accessor.

2. DockerTarget.__init__ example is misleading (docs/concepts/architecture.rst lines 59–61)
   The docs show:

   class DockerTarget(Target):
       def __init__(self):
           super().__init__(capabilities={"exec", "file_transfer", "restart"})

   The actual code takes a mandatory container argument and calls super().__init__() with no capabilities argument — the base capabilities come from Target.REQUIRED_CAPABILITIES automatically. The capability set is correct, but the constructor signature and how capabilities are registered is wrong. Since this is a concepts page and not API docs, consider simplifying the example or adding a note that it's illustrative rather than literal.

3. QEMU ping / ping_lost listed as capabilities (docs/concepts/itf_architecture.puml line 28)
   QEMU_CAPABILITIES in the source is ["ssh", "sftp"] (plus inherited exec, file_transfer, restart). ping() and ping_lost() are helper methods on QemuTarget, not registered capabilities — has_capability("ping") returns False. The PUML diagram should remove them from the capabilities box. The text in plugins.rst is more carefully worded ("plus ping/ping_lost network-testing helpers") and is fine as-is.

Minor observations

• Hardcoded commit hash in get_started.md: The git_override example uses commit = "86e6399abc...". The "replace with the latest commit" note helps, but copy-pasters will likely miss it.
• Hardcoded version in docs/conf.py: version = "0.2.0" will need manual updates on each release. Worth considering whether this can be sourced from MODULE.bazel.
• Undocumented Target methods: The base class also exposes execute_async(), has_all_capabilities(), has_any_capability(), add_capability(), remove_capability(), and wrap_exec(). Fine for an initial version, but worth noting for future reference docs.

[ltekieli]

One more thing — the PR currently has 30 commits with a lot of back-and-forth (fixups, merge commits, co-authored suggestions). Before merging, I'd suggest squashing them down into three logical commits:

1. docs-as-code setup — MODULE.bazel dep, .bazelrc Java config, BUILD target, .gitignore, docs/conf.py
2. docs content — all pages under docs/ (how-to guides, reference, concepts, architecture diagram, stub sections)
3. CI setup — docs.yml workflow

This keeps the history clean and makes it easy to revert or cherry-pick each concern independently.

[MaximilianSoerenPollak]

Hey @clanghans, I took a look at the workflow security setup. The current docs.yml uses pull_request_target, which is risky because the reusable workflows from cicd-workflows check out the PR's head ref and then run bazel run on it. Under pull_request_target that code executes with a GITHUB_TOKEN that has contents: write, pages: write, and id-token: write — so a malicious fork PR could get arbitrary code execution with write access to the repo and Pages.

This we most likely should fix everywhere if this is still an issue in some places.

[clanghans]

Hey @clanghans, I took a look at the workflow security setup. The current docs.yml uses pull_request_target, which is risky because the reusable workflows from cicd-workflows check out the PR's head ref and then run bazel run on it. Under pull_request_target that code executes with a GITHUB_TOKEN that has contents: write, pages: write, and id-token: write — so a malicious fork PR could get arbitrary code execution with write access to the repo and Pages.

This we most likely should fix everywhere if this is still an issue in some places.
@MaximilianSoerenPollak what do you mean with everywhere? I don't see the issue in this repo anymore, but I am not an github actions specialist.

[MaximilianSoerenPollak]

This we most likely should fix everywhere if this is still an issue in some places.
@MaximilianSoerenPollak what do you mean with everywhere? I don't see the issue in this repo anymore, but I am not an github actions specialist.

It wasn't meant as everywhere in this repo but more like an esclipse-score wide everywhere. Not specifically for this repo. Sorry for making it vague