docs: reorganize toctree into basic→advanced sections, rewrite user-guide landing

[FBumann]

Stacked on top of #680.

What this PR does

A second pass on the docs that reorganizes the top-level structure for a basic→advanced flow, tightens the boundary between Getting Started and the User Guide, restructures the API reference, and cleans up a handful of latent rendering issues that were dragging the build.

Toctree reorganization

index.rst had a 16-item flat User Guide bag mixing core mechanics, advanced features, troubleshooting, remote solving, migration, and FAQ-style pages. Split into focused sections with a clear reading order:

Getting Started → User Guide → Examples → Advanced Features →
Solving → Troubleshooting → Comparisons → Reference

• Renamed Benchmarking → Comparisons (both child pages are comparisons with JuMP / Pyomo, not benchmarks in the regression-tracking sense). benchmark.rst H1 became Performance comparison so the page title matches the section framing — syntax.rst was already titled Syntax comparison.
• Renamed Tutorials → Examples (every notebook in the docs is tutorial-style, the name was overloaded).
• Examples sits immediately under User Guide — reader finishes the core building blocks, then sees an end-to-end worked problem.

Getting Started → User Guide bridge

Three small but real gaps before this PR:

• The coordinates notebook ended without acknowledging the next step.
• user-guide.rst was a one-paragraph stub.
• The User Guide landing's own H1 was User Guide, duplicating the sidebar caption.

Fixed by:

• Adding a Where to next cell at the end of create-a-model-with-coordinates that links forward to the User Guide overview. (Initially tried :doc: cross-refs — those only resolve inside RST contexts; switched to markdown links pointing at .ipynb files, which nbsphinx rewrites to the rendered .html targets.)
• Rewriting user-guide.rst as a roadmap that explicitly references the Getting Started content and frames the User Guide as the depth pass on the same surface.
• Renaming the landing H1 to Overview.

API reference restructure (api.rst)

Replaced the alphabetic flat dump per class with a layered structure that puts the surface 90% of users reach for at the top, supporting classes in the middle, and genuinely rare-use surface at the bottom.

Top sections are task-oriented (Model methods grouped by what the user is doing):

• Creating a model, Inspecting a model, Modifying a model, Solving, Post-solve access, Diagnostics, IO, Top-level helpers

Classes under the hood keeps the supporting types together (Variable, Variables, LinearExpression, Constraint, Constraints, Objective, Piecewise), each with thematic subgroups (Attributes / Operations / Conversion / Post-solve etc.) rather than alphabetic dumps. autosummary renders each subgroup as a name + first-line-of-docstring table, so the page becomes scannable.

A new Advanced umbrella at the bottom for surface most users don't reach for:

• QuadraticExpression, CSRConstraint, bulk variable operations (Variables.fix/unfix/relax/unrelax), auto-reformulation (Model.reformulate_sos_constraints), remote solving (RemoteHandler), warning classes.

Curated to drop internal escape hatches and helpers:

• Model.to_gurobipy / to_highspy / to_mosek / to_cupdlpx — power-user escape hatches.
• Model.linexpr — arithmetic on Variable is the natural path.
• Constraints.format_labels, Constraints.coefficientrange — internal diagnostics.
• LinearExpression.from_rule, LinearExpression.from_constant — niche constructors.
• Constraint.freeze / .mutable, CSRConstraint.freeze / .mutable — CSR backend plumbing.
• ScalarVariable, ScalarLinearExpression — internal types.
• solvers.PIPS — stub that raises NotImplementedError.

Kept: Objective (with the post-solve fields a reader cares about: value, sense, expression, is_linear, is_quadratic), EvolvingAPIWarning / PerformanceWarning (called out under Warnings as filterwarnings targets).

PiecewiseFormulation is the return type of add_piecewise_formulation, not a construction helper — moved out of Creating a model into its own Piecewise subsection under Classes under the hood, grouped with the lower-level tangent_lines helper.

Source-side fixes that fell out of the restructure

The new api.rst structure exposed 14 properties whose autosummary table cell was blank because they had no docstring. Added a single-line description to each:

• Model.is_linear / is_quadratic / type
• BaseExpression.vars / coeffs / const (fixes both LinearExpression and QuadraticExpression entries through inheritance)
• Objective.is_linear / is_quadratic
• PiecewiseFormulation.method / convexity (inline attribute docstrings on the dataclass fields)
• OptionSettings class docstring (so the top-level options instance picks up a description)

While in piecewise.py, also dropped the duplicated literal value lists from the class-level Attributes block — now refers to the PWL_METHOD / PWL_CONVEXITY type aliases so there's a single source of truth for the allowed values.

To make those references resolve as actual links (rather than rendering as plain <code>):

• Added docstrings to PWL_METHOD, PWL_METHODS, PWL_CONVEXITY, PWL_CONVEXITIES in linopy/constants.py.
• Listed all four in api.rst under the Piecewise subsection so autosummary generates dedicated pages.
• Switched the cross-references in PiecewiseFormulation.method / .convexity and in constants.py to the fully-qualified form (:data:\~linopy.constants.PWL_METHOD``) so they resolve from whichever module they're rendered in.

Notebook rendering fixes

• Three RST admonitions in markdown cells (creating-expressions cells 13 + 17, creating-variables cell 41) had a blank line between the directive and a tab-indented body. CommonMark ate the indented block as a code block, so nbsphinx saw an empty directive and Sphinx emitted "Content block expected for the … directive" build errors. Fixed by using the convention already working elsewhere in the same notebooks (no blank line, 3-space indent).
• The first cell of solve-on-remote.ipynb had literal \n sequences in its source instead of real newlines (plus a stray trailing quote). The markdown rendered as one run-on line, Sphinx emitted four "SSH:nbsphinx-math" file-not-found and inline-interpreted-text warnings. Cell rewritten with proper line breaks.

intersphinx

The sphinx.ext.intersphinx extension was loaded in conf.py but had no intersphinx_mapping — cross-refs to xarray, numpy, pandas, etc. were silently unresolved. Added mappings for python, numpy, pandas, xarray, scipy, dask.

Build

sphinx-build runs clean. The remaining warnings are pre-existing docstring formatting issues in linopy/ source (CSRConstraint, Model.solve) — separate cleanup.

🤖 Generated with Claude Code