docs(language): the six rules every walk through a relation keeps

[FBumann]

Prompt: We defined a few rules for the relations, but we need to work them into the docs. Everything should be clear and easy to read and understand.

Note

The following content was generated by AI.

What this changes

dimensions.md states the six rules a sum or at through a relation keeps, once, under one heading, each with the example or refusal that shows it. Docs only. It replaces #537 and stacks on #540, so that the partition section can say a partition keeps rule 3 in full.

• The bullets that stated rules 2, 3, 4 and 5 in other words are folded into the rules, so no rule is on the page twice. The three bullets left are about the shape of the call: lists, into= needs by=, one table per call.
• A table beside the worked example shows what each of its three calls consumes, joins on and produces, with the operand and result frames. Rule 1 is then that table three times.
• The table of what each end may name follows rule 6. The five refusals stay.
• The partition section says which of the six it keeps: rules 3 and 4, both in full, now that feat(language): a partition names the value columns it groups by, so a relation may gain one without changing the call #540 makes within= required beside by=.

Why

The rules are what a change to the notation is measured against, so they need one home a reader can skim. #537 put them on the page beside the bullets that already said three of them, behind a table that introduced a second vocabulary, and under a section of their own for where they reach. This version keeps the rules and drops the rest.

Gates

pixi cannot be installed here, since the egress proxy refuses pixi.sh, so the gates ran from a uv venv on Python 3.13.

gate	result
every YAML fence in the walks section, python -m math_spec check	loads
the ten cases behind the rules, run as separate files	the six legal ones load; the four refused ones print the messages the page quotes
pytest -n auto	1298 passed, 6 skipped
pytest tests/test_docs.py	33 passed
mkdocs build --strict	clean, with the unreachable docs.python.org inventory dropped from the config for the run
prettier, typos	clean
compile-tex	not run; no model under examples/ changed in this PR

Sentence length on the page: n 126, avg 17.0, median 17, 18 over 25, against n 105, avg 17.0, median 17, 13 over 25 on main. Eight of the over-25 count are a bold lead-in and its first sentence measured as one.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q2gdGgMAdJ5ZVe8VM8tDTk

[read-the-docs-community]

Documentation build overview

📚 math-spec | 🛠️ Build #34636798 | 📁 Comparing 5de9225 against latest (f4c4ec0)

  🔍 Preview build  

8 files changed · ± 8 modified

± Modified

• examples/operators/index.html
• examples/pypsa_multi_period/index.html
• reference/notation/index.html
• reference/language/dimensions/index.html
• reference/language/expressions/index.html
• reference/language/operators/index.html
• reference/math_spec/operators/index.html
• reference/math_spec/program/index.html