Skip to content

docs(v1): move arithmetic-convention specs into doc/ as published rst - #861

Merged
FBumann merged 1 commit into
feat/arithmetic-conventionfrom
docs/specs-placement
Jul 22, 2026
Merged

docs(v1): move arithmetic-convention specs into doc/ as published rst#861
FBumann merged 1 commit into
feat/arithmetic-conventionfrom
docs/specs-placement

Conversation

@FBumann

Copy link
Copy Markdown
Collaborator

Stacked on #717 — relocating the v1 arithmetic-convention specs into the published docs.

Note

Generated by AI (Claude Opus 4.8) per the placement decision: move the spec files into doc/, keep the scaffolding internal.

What & why. The load-bearing specs (convention.md, goals.md, legacy-removal.md) lived in arithmetics-design/, which Sphinx never rendered. This moves them into the docs site so they're discoverable, and keeps the code's §N / path references pointing somewhere real.

  • Converted md → rst under doc/design/ (rst, not markdown, so no myst-parser dependency) and wired into a new "Design & Internals" toctree in doc/index.rst.
  • Updated every path reference: linopy/semantics.py, the five # LEGACY: remove at 1.0 — see … comments in linopy/expressions.py, the test_legacy_violations.py header, and the scaffolding files (open-items.md, docs-plan.md) that link to them.
  • release_notes.rst / migrating-to-v1.rst now use an internal :doc: cross-reference to the rendered convention page instead of a blob/master/... URL.
  • The three process files (docs-plan.md, open-items.md, multiindex-feasibility.md) stay in arithmetics-design/ as internal notes, per the agreed scope.

Note:convention.md §11's MultiIndex snippet was already fixed by #856, so no content change was needed there — this PR is purely relocation + reference updates.

Verification:sphinx-build exits 0, all three pages render, no new warnings (count 891→890, just a title-underline fix); ruff clean; the convention test suite passes.

How the build was validated

The repo's docs extra pins numpy<2 while benchmarks pins 2.4.6, so a full uv sync can't resolve — validated in an isolated .[docs] env instead. Built with -D nbsphinx_execute=never (notebooks need solvers) to check toctree + :doc: resolution + rst syntax without executing notebooks.

Relocates the load-bearing v1 specs out of the untracked-by-Sphinx
arithmetics-design/ folder into the rendered docs site:
- Convert convention.md / goals.md / legacy-removal.md → reStructuredText
under doc/design/ and wire them into a "Design & Internals" toctree in
doc/index.rst. rst (not markdown) so no myst-parser dependency is needed.
- Update every path reference: linopy/semantics.py and the five
`LEGACY: remove at 1.0` comments in linopy/expressions.py, the
test_legacy_violations.py header, and the arithmetics-design/ scaffolding
files (open-items.md, docs-plan.md) that link to them.
- release_notes.rst and migrating-to-v1.rst now cross-reference the rendered
convention page via :doc: instead of a GitHub blob URL.
The three process/scaffolding files (docs-plan.md, open-items.md,
multiindex-feasibility.md) stay in arithmetics-design/ as internal notes.
Docs build clean (sphinx-build exit 0, all three pages render, no new
warnings); ruff + the convention test suite pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@FBumann
FBumann merged commit 89bb293 into feat/arithmetic-conventionJul 22, 2026
3 checks passed
@FBumann
FBumann deleted the docs/specs-placement branch July 22, 2026 09:07
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@FBumann@FabianHofmann