[FabianHofmann]

Supersedes #704 (closed), whose section structure this reuses.

Note

The following content was generated by AI.

Changes proposed in this Pull Request

Moves the documentation from Sphinx to MkDocs with the Material theme and aligns the layout with the PyPSA documentation.

• Layout: five top tabs, as in PyPSA: Home, User Guide, Examples, API Reference, Contributing. The User Guide uses the sections from docs: restructure and refresh the documentation guides #704: Creating Models, Modifying Models, Models from Specs, Solving, Advanced Formulations, Troubleshooting, Coming from Other Tools, Design & Internals. Home gets a landing page with quick-link cards plus Features, Citing and License pages.
• Pages: all rst pages are converted to Markdown. Sphinx roles become mkdocstrings autorefs ([`Model.solve`][linopy.model.Model.solve]), directives become admonitions.
• API reference: api.rst is split into per-topic mkdocstrings pages under doc/api/ that keep its curated grouping. Restrict windows and the error classes referenced from the guides are added.
• Notebooks: moved from examples/ into doc/ and rendered with mkdocs-jupyter. They're executed at build time; LINOPY_DOCS_EXECUTE=false skips execution for local work. Markdown cells go through MkDocs' own pipeline (markdown_cell_processor: mkdocs), so admonitions and API cross-references work inside notebooks. Leftover .. note:: directives in notebook cells are converted.
• Redirects: mkdocs-redirects maps the former page names to their new locations.
• Repo config: updated the docs extra in pyproject.toml, .readthedocs.yaml (mkdocs builder, fail_on_warning: true), the notebook CI path, the pre-commit nbstripout exclude, .gitignore (it previously ignored doc/api), README, AGENTS.md, CONTRIBUTING.md and the contributing guide.
• Small fix: malformed parameter section in the assert_conequal docstring.

Zensical

Material for MkDocs reaches end of life on 5 May 2027; Zensical is its successor. Apart from mkdocs-jupyter, the config only uses features that Zensical supports. A test build of the same mkdocs.yml with Zensical 0.0.74 builds everything except the notebooks, which Zensical can't render yet. Once it can, switching should only mean changing the build command.

Follow-ups

• Old Sphinx URLs (/creating-variables.html) need Read the Docs' "HTML to clean URL" redirect, which is set in the RTD dashboard.
• Notebook pages lose the Binder link; they have a download button instead.

Verification

• mkdocs build --strict passes with notebooks executed (Gurobi installed) and with LINOPY_DOCS_EXECUTE=false.
• pre-commit run passes on all changed files.
• pytest test/test_testing.py passes.
• The Read the Docs build has not been run yet; this PR triggers it.

Checklist

• AI-generated content is marked (see AGENTS.md).
• Code changes are sufficiently documented; i.e. new functions contain docstrings and further explanations may be given in doc.
• Unit tests for new features were added (if applicable).
• A note for the release notes doc/release-notes.md of the upcoming release is included.
• I consent to the release of this PR's code under the MIT license.

---

Generated by Claude Code

[FBumann]

@FabianHofmann Mkdocs has some issues lately as far as I know regarding the maintainers.

Not sure if it's worth doing until zensical is fully stable. The docs in mathspec and specsolve are done with zensical

[codspeed]

Merging this PR will not alter performance

✅ 181 untouched benchmarks
⏩ 181 skipped benchmarks¹

---

_{Comparing docs/mkdocs-material (4f7e6d0) with master (c1d48d4)}

Footnotes

1. 181 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[FabianHofmann]

@FBumann yes, zensical compat is in here, so switching at any time is possible.