docs: the composition how-to builds a component library from terms each file adds to a sum

[FBumann]

Prompt: Fix 4 too in a separate docs pr

Note

The following content was generated by AI.

What this changes

The how-to now composes its component library from an empty: true sum that each file adds a term to, which matches the tutorial and the PyPSA split. The library example keeps its flow-per-port coupling and says why it uses it.

Why

Method, gate output, alternatives

The problem on main. docs/howto/compose.md taught the port surface: Port_p, pinned by each component with at(...). It said that a component "pins the flow at its own port rather than adding a term to the balance". But docs/several-files.md and examples/pypsa/ teach the empty sum with term:. So a reader saw two patterns and a how-to that argued against the tutorial.

What changed.

• The "A library of components" section. It now has network.yaml (an empty Bus_injection and its balance), generator.yaml and load.yaml (each adds a term), and a step 4 that adds store.yaml without touching the network.
• "A column read one way and introduced another". This section now shows emissions.yaml, which reads Generator_p as binary, and quotes the real refusal.
• The term-naming advice. It now uses the example's names.
• The library page and the how-to link to each other. docs/examples/library/index.md gets one paragraph: it couples through Port_p so that the solved flow at each port can be read back. Where no one reads that flow, the sum needs no variable. The how-to ends with one sentence that links back to it.

Checks.

• Every YAML fence in the new section is loaded with python -m mathspec check.
• The merge results (Generator_injection + Load_injection, then + Store_injection) and all three quoted refusals come from running the files. The files are not committed, because no test reads this page.

Gates.

• pixi run lint: clean.
• pixi run test: 2560 passed.
• docs-build did not run to the end here. --strict aborts because the proxy blocks docs.python.org/3/objects.inv, and main fails the same way in this container. The only warning is the unresolved pathlib.Path from that inventory, so there is no dead anchor.
• No file under examples/ changed, so compile-tex is not affected.

Interaction with #761. This PR branches from main and uses its dict form of merge. If #761 lands first, I merge main into this branch and change the two calls to lists. The how-to lines they touch overlap.

What this PR does not do.

• It does not change the library example files or their generated pages.
• It does not decide point 1, moving term: onto the named expression.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AApRDPxpZcALYLrFMXEF7z

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34807995 | 📁 Comparing bf404b1 against latest (22cdebd)

  🔍 Preview build  

3 files changed

± changelog/index.html
± examples/library/index.html
± howto/compose/index.html