Add documentation pages on the models

CONTRIBUTING.md

@@ -290,6 +290,15 @@ and open `docs/_build/html/index.html`. Any warning fails the build, here and in
 broken cross-reference, a malformed docstring, or a page missing from every table of
 contents. A new public module needs an entry in one of the pages of `docs/api/`.
 
+The diagrams on the model pages are drawn in TikZ, in
+[`docs/models/diagrams/`](docs/models/diagrams), with their colours and styles in a shared
+preamble. The SVGs built from them are committed, so the site builds without TeX. After
+changing a diagram, rebuild its SVG (this needs TeX with TikZ, and `dvisvgm`):
+
+```bash
+python docs/models/diagrams/build.py capsule    # or no name, for every diagram
+```
+
 ## Releasing
 
 For maintainers. PyTES uses [semantic versioning](https://semver.org), with pre-releases

changelog.d/48.feature.md

@@ -0,0 +1 @@
+New documentation pages on the models: what every model shares, and a page for each family, the finned tube and the packed bed, with the geometry, the equations and the options, illustrated with diagrams drawn in TikZ (`docs/models/diagrams/`).

docs/_static/pytes.css

@@ -62,3 +62,12 @@ html[data-theme="dark"] {
   border-radius: 0.15em;
   box-shadow: 0 0 0 1px var(--pst-color-border, rgba(0, 0, 0, 0.25));
 }
+
+/* Model diagrams (docs/models/diagrams) on a light card in both themes, undimmed in dark
+   mode (the dark-light class opts them out of the theme's filter) */
+.bd-content img.pytes-diagram {
+  background-color: #ffffff;
+  padding: 0.75rem;
+  border-radius: 0.4rem;
+  box-shadow: 0 0 0 1px var(--pst-color-border, rgba(0, 0, 0, 0.12));
+}

docs/getting_started.md

@@ -31,15 +31,16 @@ your own to `pybamm.Simulation` to change them.
 
 | Family | Models | Storage |
 |---|---|---|
-| Finned tube | {class}`~pytes.SharpFrontModel`, {class}`~pytes.MushModel` | PCM around tubes with metal fins (homogenised or resolved) |
-| Packed bed | {class}`~pytes.PackedBedModel` | a bed of spherical PCM capsules |
+| [Finned tube](models/finned_tube.md) | {class}`~pytes.SharpFrontModel`, {class}`~pytes.MushModel` | PCM around tubes with metal fins (homogenised or resolved) |
+| [Packed bed](models/packed_bed.md) | {class}`~pytes.PackedBedModel` | a bed of spherical PCM capsules |
 
 Every model takes `options={"storage along flow path": "averaged"}` for a faster variant
 with one storage cross-section standing for the average along the flow, and the packed bed
 takes `options={"storage element": "lumped"}` for capsules at a uniform temperature
 ([Lumped capsule](examples/lumped_capsule.ipynb)). Each model is a fixed composition of
 submodels (a fluid, a storage and a coupling, plus the device-level energy), listed in
-`model.submodels`; `model.print_submodel_info()` describes them.
+`model.submodels`; `model.print_submodel_info()` describes them. The
+[model pages](models/index.md) give the geometry and the equations of each family.
 
 ## Conventions
 

docs/index.md

@@ -16,6 +16,7 @@ ordinary PyBaMM model, so PyBaMM's simulations, solvers and plots work on it dir
 
 - [**Getting started**](getting_started.md): install PyTES and run a first model.
 - [**Examples**](examples/index.md): notebooks for each capability.
+- [**Models**](models/index.md): the model families, their geometry and their equations.
 - [**Parameter values**](parameter_values.rst): the parameter sets and layers PyTES
   provides, with their sources.
 - [**Plot colours**](plot_colours.md): the PyTES colour cycles and colourmaps, and why.
@@ -28,6 +29,7 @@ ordinary PyBaMM model, so PyBaMM's simulations, solvers and plots work on it dir
 
 getting_started
 examples/index
+models/index
 parameter_values
 plot_colours
 api/index

docs/models/diagrams/build.py

@@ -0,0 +1,66 @@
+"""
+Build the SVG model diagrams from their TikZ sources.
+
+Each ``<name>.tex`` in this folder (other than the shared preamble) is compiled with
+``latex`` and converted with ``dvisvgm`` to ``<name>.svg`` next to it, with the text turned
+into paths so that the SVGs need no fonts. The SVGs are committed, so the documentation
+builds without TeX; rebuild them after changing a source::
+
+    python docs/models/diagrams/build.py            # every diagram
+    python docs/models/diagrams/build.py capsule    # only some
+
+Needs a TeX distribution with TikZ and the standalone class, and dvisvgm (on Debian or
+Ubuntu: ``texlive-pictures texlive-latex-extra dvisvgm``).
+"""
+
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+HERE = Path(__file__).parent
+PREAMBLE = "pytes-diagrams.tex"
+
+
+def build(source):
+    """Compile one TikZ source to an SVG next to it"""
+    with tempfile.TemporaryDirectory() as tmp:
+        shutil.copy(HERE / PREAMBLE, tmp)
+        shutil.copy(source, tmp)
+        result = subprocess.run(
+            ["latex", "-interaction=nonstopmode", "-halt-on-error", source.name],
+            cwd=tmp,
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            sys.exit(f"{source.name}: latex failed\n{result.stdout[-2000:]}")
+        dvi = Path(tmp) / source.with_suffix(".dvi").name
+        svg = source.with_suffix(".svg")
+        subprocess.run(
+            [
+                "dvisvgm",
+                "--no-fonts",
+                "--exact-bbox",
+                "--optimize",
+                str(dvi),
+                "-o",
+                str(svg),
+            ],
+            check=True,
+            capture_output=True,
+        )
+    print(f"built {svg.relative_to(HERE)}")
+
+
+def main(names):
+    sources = sorted(p for p in HERE.glob("*.tex") if p.name != PREAMBLE)
+    if names:
+        sources = [p for p in sources if p.stem in names]
+    for source in sources:
+        build(source)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])