Mesh guard and gallery

.clang-format

@@ -1,5 +1,3 @@
----
-Language:        Cpp
 # BasedOnStyle:  LLVM
 AccessModifierOffset: -2
 AlignAfterOpenBracket: Align

.gitignore

@@ -177,3 +177,6 @@ _probe*.py
 *.vtu
 *.pvd
 *.png
+
+# Interactive scenes the examples export for the gallery
+examples/*.vtksz

README.md

@@ -5,34 +5,29 @@ This package contains a collection of tools for scientific computing with a focu
 Many users that are transitioning from legacy FEniCS to FEniCSx may find the transition difficult due to the lack of some functionalities in FEniCSx.
 This package aims to provide some of the functionalities that are missing in FEniCSx.
 
-See the [documentation](https://scientificcomputing.github.io/scifem/) for the API reference and runnable examples of the features below.
+<!-- The book's front page, index.md, shows its gallery here -->
 
-## Backwards compatibility
-We aim to support the last two stable releases of DOLFINx. Sometimes features are supported for longer if need be.
-
-Some features might depend on functionality added to DOLFINx, which means that they won't be backwards compatible.
+# Features
 
-## Features
-
-### Meshes, tags and submeshes
+## Meshes, tags and submeshes
 
 - Create `MeshTags` from a list of tags and corresponding locator functions.
 - Extract a submesh of entities of any co-dimension.
 - Locate the interface between two subdomains, and the exterior facets of a subdomain.
 
-### Periodic meshes
+## Periodic meshes
 
 - Build a periodic mesh (MPI supported), by merging the vertices on opposite sides of the domain. The periodicity lives in the topology, so a continuous function space on the result is periodic with no constraint matrix, as opposed to [DOLFINx_MPC](https://github.com/jorgensd/dolfinx_mpc).
 - Take the vertex pairs from the `$Periodic` section of a gmsh model rather than from the coordinates.
 - Move mesh tags onto a periodic mesh, and move a solution back onto the mesh it was built from. Required for post-processing with Pyvista or Paraview.
 - Diagnose the two ways an input mesh can be unsuitable, a missing ghost layer and cells that collapse onto each other across a seam.
 
-### Function spaces and degrees of freedom
+## Function spaces and degrees of freedom
 
 - Spaces of functions that are constant on each subdomain.
 - Maps between degrees of freedom and vertices, in both directions.
 
-### Assembly, sources and boundary conditions
+## Assembly, sources and boundary conditions
 
 - Assemble a scalar or a norm over all processes in a single call.
 - Point sources for usage in DOLFINx (>=v0.8.0).
@@ -41,28 +36,38 @@ Some features might depend on functionality added to DOLFINx, which means that t
 - Interpolate an expression onto the degrees of freedom of a set of facets.
 - Helpers for the PETSc vector operations that surround a solve: zeroing, ghost updates, lifting and boundary conditions.
 
-### Evaluation, interpolation and geometry
+## Evaluation, interpolation and geometry
 
 - Evaluate a function at arbitrary points, in parallel.
 - Find the extrema of a UFL expression within each cell, or over a whole domain.
 - Project points onto the closest point of a mesh.
 - Build interpolation matrices from any `ufl.core.expr.Expr` into a compatible space.
 - Interpolate from a mesh onto a submesh of its facets, and extend a function on such a submesh back into the mesh, zero away from the facets, into Lagrange, H(div) or H(curl) spaces.
 
-### Output
+## Output
 
 - Save quadrature functions as point clouds.
 - Save any function that can tabulate dof coordinates as point clouds.
 
-### Biomedical
+## Biomedical
 
 - Read MRI data onto a mesh, as a function or as cell tags. Requires the `biomed` extra.
 
-## Installation
+# Documentation
+
+The [documentation](https://scientificcomputing.github.io/scifem/) has the API reference and runnable examples of the features above.
+
+# Backwards compatibility
+
+We aim to support the last two stable releases of DOLFINx. Sometimes features are supported for longer if need be.
+
+Some features might depend on functionality added to DOLFINx, which means that they won't be backwards compatible.
+
+# Installation
 
 The package is partly written in C++ and relies on `dolfinx`. Users are encouraged to install `scifem` with `pip` in an environment where `dolfinx` is already installed or with `conda`.
 
-### `pip`
+## `pip`
 To install the package with `pip` run
 
 ```bash
@@ -77,7 +82,7 @@ python3 -m pip install --no-build-isolation git+https://github.com/scientificcom
 
 Note that you should pass the flag `--no-build-isolation` to `pip` to avoid issues with the build environment, such as incompatible versions of `nanobind`.
 
-### `spack`
+## `spack`
 The spack package manager is the recommended way to install scifem, and especially on HPC systems.
 For information about the package see: [spack-package: py-scifem](https://packages.spack.io/package.html?name=py-scifem)
 First, clone the spack repository and enable spack
@@ -115,14 +120,14 @@ Finally, note that spack needs some packages already installed on your system. O
 ```bash
 apt update && apt install gcc unzip git python3-dev g++ gfortran xz-utils -y
 ```
-### `conda`
+## `conda`
 
 To install the package with `conda` run
 
 ```bash
 conda install -c conda-forge scifem
 ```
 
-## Having issues or want to contribute?
+# Having issues or want to contribute?
 
 If you are having issues, feature request or would like to contribute, please let us know. You can do so by opening an issue on the [issue tracker](https://github.com/scientificcomputing/scifem/issues).

_config.yml

@@ -30,6 +30,9 @@ parse:
 
 
 sphinx:
+  # Copies the demos' animations for the gallery on the front page
+  local_extensions:
+    demo_gallery: docs/_ext
   extra_extensions:
   - 'sphinx.ext.autodoc'
   - 'sphinx.ext.napoleon'

_static/open-linked-dropdown.js

@@ -0,0 +1,37 @@
+// Open a collapsed `:class: dropdown` admonition when the page is navigated to
+// it.
+//
+// sphinx-togglebutton collapses with a `toggle-hidden` class rather than a
+// native
+// `<details>`, so the browser cannot expand it for us and a link to a target
+// inside one would scroll to a box that is still shut.
+(function() {
+function openTarget()
+{
+  if (!window.location.hash)
+  {
+    return;
+  }
+  var target = document.getElementById(window.location.hash.slice(1));
+  if (!target)
+  {
+    return;
+  }
+  var box = target.closest('.admonition.toggle');
+  if (box && box.classList.contains('toggle-hidden'))
+  {
+    box.classList.remove('toggle-hidden');
+    // Keep the button's label and aria-expanded in step; togglebutton exposes
+    // this.
+    if (typeof window.syncAllToggleHints === 'function')
+    {
+      window.syncAllToggleHints();
+    }
+    box.scrollIntoView({block : 'center'});
+  }
+}
+
+// togglebutton adds `toggle-hidden` on DOMContentLoaded, so run after it.
+window.addEventListener('load', openTarget);
+window.addEventListener('hashchange', openTarget);
+})();

_toc.yml

@@ -2,8 +2,12 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: README
+root: index
 parts:
+  - caption: Getting started
+    chapters:
+      - file: "docs/installation"
+      - file: "docs/compatibility"
 
   - caption: Periodic meshes
     chapters: