📝 Make documentation executable and checked

[burgholzer]

🤖 AI text below 🤖

Description

A successful documentation build could reuse stale notebook results, accept
failed CLI commands, and publish broken navigation. Several DD equations and
public capability statements were also incorrect. This change addresses all
twelve groups in the documentation audit:

• Correct DD equations and their illustration, normalization and complexity
  explanations, and compiler/Qiskit/calibration contracts.
• Execute complete local workflows, check their results, force fresh notebooks,
  isolate QDMI discovery, and fail on CLI or Doxygen errors.
• Check generated file and fragment links, use valid Doxygen static navigation,
  and expose the C++ reference through the normal toctree and agent index.
• Separate exhaustive Qiskit contracts from the tutorial, improve visible
  results and accessible figures, and remove redundant configuration and assets.

The rendered installation, contribution, and tooling changes come from
Templates #438.
That change is merged, and the templating workflow pins its main commit
38a2369c8303887135af5e98d9e7003ed267b613. Existing Sphinx, MyST-NB, and native Doxygen tooling is retained;
no dependency or library runtime change is introduced.

The changes have been reassessed and replayed on upstream main 0c3fac2cb.
Executable target-compilation and DDSIM examples use TargetEnvironment and
PayloadSpecification. The Qiskit reference preserves the merged custom-gate,
scalar-folding, and snapshot contracts; merged OpenQASM, QIR, DDSIM, benchmark,
and generated-header lint updates are retained.

Validation: the full HTML build with Read the Docs' Doxygen 1.9.8 and generated
local links passed. All nine notebooks (56 code cells) executed without error or
stderr outputs. External linkcheck, full lint, and both navigation regression
tests passed.

The standard cpp-lint session excludes public headers and selected no files.
A separate full-header check reported five existing naming/conversion warnings
in Client.hpp, reproduced against the original header; none concern the edited
comments. Generated figures and image alternatives were inspected; the browser
preview could not connect to localhost. Hosted CI and human review are pending.
No remote hardware or provider deployment was exercised.

Codex implemented and validated this change under explicit user authorization.
No changelog or migration entry is needed for these documentation and validation
changes.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!