docs: the composition how-to shows a sum that one file defines and other files add terms to

[FBumann]

Prompt: Do a stacked PR fixing all of this

Note

The following content was generated by AI.

What this changes

This fixes the four doc findings from a review of #763. It adds a define-then-add step to the how-to, corrects a stale sentence in the tutorial, states what a one-line override patch keeps, and lists the Terms rules in the reference.

Why

The docs of #763 had one sentence that contradicts the code, one behaviour change they did not state clearly, no example of the case the second prompt of #763 asked for, and dense reference prose.

Changes, method, gates, what is not done

Changes.

• docs/howto/compose.md, new step 5: network_slack.yaml defines Bus_injection as Bus_slack. merge(['network_slack.yaml', 'generator.yaml', 'load.yaml']) gives Bus_slack + Generator_injection + Load_injection, with the definer's dims: and description. I ran that merge on the head of feat/adds-to to get this result.
• docs/howto/compose.md, the patch step: a one-line patch replaces only the body. The entry keeps dims:, the description and adds_to:, so the new body carries no dimension outside the kept dims:. On main, the string replaced the whole entry. I checked both halves: override with '2 * a' kept dims: [g] and the description, and 'b' over [s, g] was refused with a DimensionError.
• docs/howto/compose.md, the adds_to: table row: cut to the definer rule, with a link to the Terms section.
• docs/several-files.md, "Leave the network out": the prose said no file declares injection. It now says no file reads it, other than the two files that add to it. This matches the message printed below it.
• docs/reference/language/declarations.md, Terms: the load-time checks and the merge rules are now two bulleted lists with bold lead-ins. The "one file alone reads" rule now states its reason. Two unevenly wrapped paragraphs are rewrapped.

Sentence measure (the docs-writing skill's script):

Page	Before	After
Terms section	n 28, avg 17.5, median 19, over 25: 2	n 27, avg 18.2, median 19, over 25: 3
compose.md	n 59, avg 15.4, median 15, over 25: 5	n 64, avg 15.4, median 15, over 25: 5

The three Terms sentences over 25 words are list items. The script joins two of them to their bold lead-ins.

Gates.

• pixi run lint: clean.
• pixi run ci: test gave 2611 passed. docs-build stopped on one warning, the unresolved pathlib.Path autoref: the session's proxy blocks docs.python.org/3/objects.inv. It reported no dead anchor. compile-tex did not run, because ci stopped before it. No file under examples/ changed.
• tools.changelog entry accepts this title against the base changelog.
• The new YAML in compose.md is a hand-written fence that no test reads. I loaded and merged it by hand, as above.

Not done.

• feat(language): a term names the sum it adds to with adds_to:, and no file marks a sum as open #763 does not yet name the override change as a break. This PR does not edit feat(language): a term names the sum it adds to with adds_to:, and no file marks a sum as open #763's body. The row to add to its "Before and after" table:
  | A one-line patch on a named expression replaces the whole entry, and drops its dims: and description | It replaces only the body, and the entry keeps dims:, the description and adds_to: |
• No code changes. The review found none to make.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BNUaTy5JqkQCjytjg1FtTv

[read-the-docs-community]

Documentation build overview

📚 mathspec | 🛠️ Build #34856746 | 📁 Comparing 26454c4 against latest (4581220)

  🔍 Preview build  

24 files changed · ± 24 modified

± Modified

• changelog/index.html
• several-files/index.html
• examples/pypsa/index.html
• howto/compose/index.html
• reference/api/index.html
• reference/program/index.html
• reference/reading/index.html
• reference/typeset/index.html
• examples/pypsa/generator/index.html
• examples/pypsa/generator_commitment/index.html
• and 14 more...