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

@FBumann FBumann commented Jul 21, 2026

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 requested a review from FabianHofmann July 21, 2026 11:45
@FBumann
FBumann merged commit 89bb293 into feat/arithmetic-convention Jul 22, 2026
3 checks passed
@FBumann
FBumann deleted the docs/specs-placement branch July 22, 2026 09:07
Sign up for free to 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