Drilldown Architecture¶
This example shows how needsvg diagrams can link directly to each
other, creating a true drill-down experience. Each SVG layer is wrapped
in an .. arch:: need element with an ID. Stage boxes use ref() to link
to the arch element of the next layer, so clicking a box jumps straight to
the detail SVG.
Tip
The pattern:
Define an
.. arch::element for each SVG layer (e.g.ARCH_PIPELINE,ARCH_BUILD).Place the
.. needsvg::block inside thearchelement’s content.In the SVG, link boxes to the next layer with
ref('ARCH_BUILD')etc.Add a back-link in each detail SVG:
ref('ARCH_PIPELINE').Add sibling links so users can jump between peer layers.
No JavaScript, no custom code – just sphinx-needs anchors.
Level 1 – CI Pipeline¶
The continuous-integration pipeline that validates every commit. |
Compile the project and produce distributable artefacts. |
Run the full test suite against the built artefacts. |
Publish documentation and release artefacts. |
Top-level view of the three pipeline stages. Click a stage to drill down. |
Level 2 – Build Stage¶
Run ruff linter and mypy type-checker. |
Build the Python wheel with hatchling. |
Detail view of the Build stage. Click any job to drill into its steps. |
Level 2 – Test Stage¶
Run pytest unit tests with coverage. |
Build Sphinx documentation and check for warnings. |
Detail view of the Test stage. Click any job to drill into its steps. |
Level 2 – Deploy Stage¶
Deploy Sphinx docs to GitHub Pages. |
Tag and publish the Python package. |
Detail view of the Deploy stage. |
Level 3 – Lint Job Steps¶
Execute |
Execute |
Detail view of the Lint job’s individual steps. |
Level 3 – Compile Job Steps¶
Install build dependencies via |
Run |
Detail view of the Compile job’s individual steps. |
Level 3 – Unit Test Job Steps¶
Run |
Execute |
Detail view of the Unit test job’s individual steps. |
Level 3 – Docs Build Job Steps¶
Auto-generate API docs from Python source with |
Run |
Detail view of the Docs build job’s individual steps. |