Doc: Expand plug, slot, hook coverage

[akcano]

No description provided.

[Copilot]

Pull request overview

This PR substantially expands the documentation around SDK plugs, slots, and lifecycle hooks. It introduces a new "Develop SDKs" how-to section (with declare-plugs-slots, configure-mount-ownership, and write-runtime-hooks guides), two new workshop-customisation how-tos (design-capability-topology, explicitly-bind-plug-slot-pairs), and dedicated explanation pages (plugs-and-slots, runtime-hooks) carved out from existing concept pages. Companion Spread tests for each how-to provide synthesized SDKs and task.yaml files that exercise the documented commands so the docs stay verifiable.

Changes:

• Add five new how-to guides and two explanation pages, restructuring existing concepts.rst files to delegate detail to the new pages.
• Add corresponding tests/docs-how-to/ Spread tests with synthesized SDKs validating each guide's commands and assertions.
• Update toctrees in docs/how-to/index.rst, docs/how-to/customize-workshops/index.rst, docs/explanation/sdks/index.rst, and docs/explanation/interfaces/index.rst.

Reviewed changes

Copilot reviewed 40 out of 40 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
docs/how-to/index.rst	Add "Develop SDKs" section to the top-level how-to index.
docs/how-to/develop-sdks/index.rst	New landing page for SDK-author how-tos.
docs/how-to/develop-sdks/declare-plugs-slots.rst	New guide on declaring mount/tunnel plugs and slots.
docs/how-to/develop-sdks/configure-mount-ownership.rst	New guide on overriding mount uid/gid/mode/read-only.
docs/how-to/develop-sdks/write-runtime-hooks.rst	New guide covering all five SDK lifecycle hooks.
docs/how-to/customize-workshops/index.rst	Add design-capability-topology and explicitly-bind entries.
docs/how-to/customize-workshops/design-capability-topology.rst	New guide for wiring SDKs in a workshop definition.
docs/how-to/customize-workshops/explicitly-bind-plug-slot-pairs.rst	New guide for resolving ambiguous autowiring.
docs/explanation/interfaces/index.rst	Toctree entry for the new plugs-and-slots page.
docs/explanation/interfaces/concepts.rst	Delegate plug/slot/binding detail to the new page; add tunnel bullet.
docs/explanation/interfaces/plugs-and-slots.rst	New consolidated explanation page on plugs, slots, wiring mechanisms.
docs/explanation/sdks/index.rst	Toctree entry for the new runtime-hooks page.
docs/explanation/sdks/concepts.rst	Replace hook/state subsections with a pointer to the new page.
docs/explanation/sdks/runtime-hooks.rst	New consolidated explanation page on lifecycle hooks and state.
tests/docs-how-to/declare-plugs-slots/{task.yaml,sdkcraft.yaml}	Spread test that packs cachekit and inspects embedded sdk.yaml.
tests/docs-how-to/configure-mount-ownership/**	Spread test with an SDK declaring four plug variants and verifying mounts.
tests/docs-how-to/write-runtime-hooks/**	Spread test exercising all five hooks via launch + refresh.
tests/docs-how-to/design-capability-topology/**	Spread test wiring provider-sdk:bin to consumer-sdk:tools.
tests/docs-how-to/explicitly-bind-plug-slot-pairs/**	Spread test for three-stage ambiguous-autowiring resolution.

Comments suppressed due to low confidence (2)

docs/how-to/develop-sdks/write-runtime-hooks.rst:223

• The verification snippet shows workshop status dev matching Status: Ready, but the test in tests/docs-how-to/write-runtime-hooks/task.yaml line 19 matches just 'Ready'. If the actual workshop status output does not include a Status: label prefix (as the test implies), the documented example is misleading. Either confirm the real output format and update one to match the other, or use a more illustrative excerpt that matches the actual CLI output.

   $ workshop status dev

     Status: Ready

tests/docs-how-to/explicitly-bind-plug-slot-pairs/task.yaml:12

• The "Stage 1" assertion on line 12 expects consumer:feed to be wired to system:mount. However, the consumer SDK declares workshop-target: /home/workshop/feed, and the test on line 25 then expects /home/workshop/feed/marker to contain from-a after the manual connect. For Stage 1, if consumer:feed is connected to system:mount, there will be no marker file under /home/workshop/feed — but the test does not exercise Stage 1 by reading the file, so this is consistent. Worth verifying though: does system:mount even satisfy a plug whose workshop-target is /home/workshop/feed (a sub-path that does not exist on the host)? If system:mount provides only the user's home/project mounts, the auto-connect might not succeed and consumer:feed might end up unconnected instead of wired to system:mount, which would cause the Stage 1 regex on line 12 to fail. Worth confirming against the actual auto-connect implementation.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

docs/explanation/interfaces/plugs-and-slots.rst:115

• These lines claim that when more than one slot matches a plug, the plug is not connected automatically and you must choose. There is no generic ambiguity-detection step in the auto-connect implementation; it evaluates policy-allowed candidates and may attempt to connect multiple slots. Consider rewording to avoid implying the system will safely leave plugs unconnected on ambiguity, and instead recommend using explicit connections: (or workshop connect) to ensure the desired pairing when multiple candidates could apply.

Autowiring becomes ambiguous
when more than one slot in the workshop matches a plug.
In that case,
the plug is not connected automatically
and you have to choose a slot yourself.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 42 out of 42 changed files in this pull request and generated 1 comment.