Docs overhaul (power sector): correctness fixes, Model Description section, generated figures

[ktehranchi]

Re-lands #776. Closes nothing new.

Why this PR exists

PR #776 ("Docs overhaul (power sector)") was merged — but into the wrong branch. At
the time two branches shared the name v1-epic: the fork branch ktehranchi:v1-epic
(the real simplify-early epic) and an upstream branch PyPSA/pypsa-usa:v1-epic that
was a stale snapshot of develop carrying none of the epic content. #776 targeted the
stale upstream one, so its squash commit (9697fb44) landed on a branch nothing else
merges from.

#775 then merged the fork's epic branch into develop. The epic itself is on
develop and correct (git diff ktehranchi/v1-epic upstream/develop -- workflow/ tests/
is empty), but the docs overhaul never travelled with it and is currently stranded.

This PR re-lands exactly that content on top of current develop.

Changes proposed in this Pull Request

Identical in substance to what was reviewed in #776 — 67 files, 53 of them under
docs/source/, no dependency changes:

• P0 correctness — fixed literalinclude scoping in the config reference (the old
  :start-at: <key>: convention matched by substring and sliced the wrong YAML block),
  completed the configtables/*.csv set (new offwind.csv, corrections across
  atlite, clustering, costs, electricity, emissions, load,
  nrel_exclusion, onwind, opts, solar, solving), and corrected the
  getting-started and power-sector data pages against the current pipeline.
• New Model Description section — model-workflow.md, model-components.md,
  model-constraints.md, model-network-schema.md, plus release-notes.md.
• Figures — regenerated _static/dag.svg, added generated figures
  (_static/generated/network_aggregation.png, example_outputs.png) with a
  docs_figures Snakemake rule and workflow/scripts/plot_docs_figures.py that
  produces them; PDF-safe figures on the sector pages and an image diet across
  _static/.
• Guard tests — tests/docs/test_docs_config.py asserts every literalinclude
  slice resolves to exactly the YAML keys it claims to document, and that
  workflow/config/ has not drifted from the canonical workflow/repo_data/config/.
• Build hygiene — .readthedocs.yaml, docs/requirements.txt, docs/source/conf.py.
• Config annotations — # docs : <NAME> anchors and inline comments in
  workflow/repo_data/config/config.{common,default,cluster}.yaml; workflow/config/config.common.yaml
  re-synced to the canonical template it had drifted from. One behavioural
  consequence to be aware of: that re-sync brings the live config.common.yaml in line
  with the template's EGS.drilling_cost: advanced, EGS.seismic_exclusion: true and
  the ucap: block, and drops the unused offshore_network.enable key. This was part
  of Docs overhaul (power sector): correctness fixes, Model Description section, generated figures #776 as reviewed.
• One non-docs line: workflow/rules/build_electricity.smk now reads
  config.get("renewable_scenarios", ["historical"])[0] instead of indexing directly,
  so the GoDEEEP horizon guard does not raise when the key is absent.

Merge resolution notes

Conflicts were epic-vs-epic (both sides carry the same epic, one as 88 commits and one
as squash 01f742f1) and were resolved to develop's content. Where develop's epic
had moved on since docs-overhaul branched, the docs were updated to match rather than
reverted:

• The rule cluster_simpl was renamed to cluster_resources on develop after this
  branch forked. Rule-name references in the user-facing pages
  (about-introduction, config-spatial, config-configuration, config-wildcards,
  model-workflow, release-notes, configtables/clustering.csv) and the walltime
  keys in config.default.yaml / config.cluster.yaml were updated accordingly. The
  script filename is still cluster_simpl.py on develop, so references to the file
  were left alone. docs/source/_static/dag.svg is a generated artifact and still
  shows the old rule label; it needs a snakemake dag re-render, which was not run here.
• develop's nrel_caps_reassign key falls inside the documented # docs : NREL_EXCLUSION
  slice, so it was added to the expected key set in tests/docs/test_docs_config.py.
• docs/source/publications.bib is byte-identical to develop — this branch never
  touched it, so the v0.9.0 entries (barnes2026b, ai2026, barnes_2026a) and the
  removal of the duplicate barnes_2026 key are preserved as-is.
• pyproject.toml and uv.lock are byte-identical to develop.

Testing

• pre-commit ran on the merge commit and passed with no file modifications.
• pytest tests/docs/ — 38 passed, 1 failed. The failure is
  test_config_tree_sync, which compares workflow/config/ against
  workflow/repo_data/config/. It only passes in a checkout where
  init_pypsa_usa.sh has populated workflow/config/; in a bare clone that
  directory holds only the tracked config.common.yaml, so the test reports the
  other templates as missing instead of skipping. This is inherited from Docs overhaul (power sector): correctness fixes, Model Description section, generated figures #776 as
  reviewed, not introduced by this merge, and is worth a follow-up to tighten the
  skip condition.
• Not run here: no Sphinx build, no snakemake invocation of any kind (so the
  docs_figures rule and the DAG re-render were not exercised), no Tier A/Tier B
  pytest run, no equivalence harness. The Read the Docs PR build on this PR is the
  first real check that the pages render.

Checklist

• I tested my contribution locally and it seems to work fine. — not ticked: the
  docs were not built locally in this pass; see Testing above.
• pre-commit passes locally. pytest -m fast was not run; pytest tests/docs/
  results are above.
• Code and workflow changes are sufficiently documented.
• Changed dependencies are added to workflow/envs/environment.yaml. — no
  dependency changes; pyproject.toml and uv.lock match develop exactly.
• Changes in configuration options are added in workflow/repo_data/config/config.default.yaml.
• Changes in configuration options are also documented in docs/source/configtables/*.csv.