Add sphinx-gallery to builds an HTML gallery of examples (#374)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.readthedocs.yaml

@@ -28,4 +28,3 @@ python:
       path: .
       extra_requirements:
         - docs
-    - requirements: docs/requirements.txt

docs/conf.py

@@ -12,6 +12,18 @@
 import os
 from pathlib import Path
 
+import pyvista
+from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper
+
+pyvista.set_error_output_file("errors.txt")
+pyvista.OFF_SCREEN = True  # Not necessary - simply an insurance policy
+pyvista.set_plot_theme("document")
+pyvista.BUILDING_GALLERY = True
+os.environ["PYVISTA_BUILDING_GALLERY"] = "true"
+
+if os.environ.get("READTHEDOCS") or os.environ.get("CI"):
+    pyvista.start_xvfb()
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -39,8 +51,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["myst_parser"]
-
+extensions = ["myst_parser", "pyvista.ext.plot_directive", "pyvista.ext.viewer_directive", "sphinx_design", "sphinx_gallery.gen_gallery"]
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
@@ -123,3 +134,19 @@
     "substitution",
     "tasklist",
 ]
+
+# -- sphinx_gallery settings -------------------------------------------------
+
+sphinx_gallery_conf = {
+    "backreferences_dir": None,
+    "doc_module": "pyvista",
+    "download_all_examples": False,
+    "examples_dirs": ["../examples/"],
+    "filename_pattern": r"\.py",
+    "first_notebook_cell": ("%matplotlib inline\n" "from pyvista import set_plot_theme\n" "set_plot_theme('document')\n"),
+    "gallery_dirs": ["./examples"],
+    "image_scrapers": (DynamicScraper(), "matplotlib"),
+    "pypandoc": True,
+    "remove_config_comments": True,
+    "reset_modules_order": "both",
+}

examples/README.rst

@@ -0,0 +1,7 @@
+.. _examples:
+
+Examples
+========
+
+A gallery of examples. Coarse meshes are used whenever possible to make the examples run
+fast. Some examples require external packages to be installed.

examples/cylinder.py

@@ -1,4 +1,10 @@
-"""scikit-gmsh package for 3D mesh generation test."""
+r"""
+Cylinder geometry example
+-------------------------
+
+Cylinder geometry example.
+
+"""
 
 from __future__ import annotations
 
@@ -9,5 +15,9 @@
 edge_source = pv.Cylinder(resolution=16)
 edge_source.merge(pv.PolyData(edge_source.points), merge_points=True, inplace=True)
 edge_source.plot(show_edges=True)
-delaunay_3d = sg.Delaunay3D(edge_source)
-delaunay_3d.mesh.shrink(0.9).plot(show_edges=True)
+
+# %%
+# Generate the mesh.
+
+alg = sg.Delaunay3D(edge_source)
+alg.mesh.plot(show_edges=True)

examples/polygon_with_hole.py

@@ -1,14 +1,21 @@
-"""scikit-gmsh package for polygon with hole mesh generation test."""
+r"""
+Polygon with hole geometry example
+----------------------------------
 
-from __future__ import annotations
+Polygon with hole geometry example.
+
+"""
 
-from shapely import Polygon
+from __future__ import annotations
 
 import skgmsh as sg
 
-polygon_with_hole = Polygon(
-    [(0, 0, 0), (0, 10, 0), (10, 10, 0), (10, 0, 0), (0, 0, 0)], holes=[[(2, 2, 0), (2, 4, 0), (4, 4, 0), (4, 2, 0), (2, 2, 0)]]
-)
+shell = [(0, 0, 0), (0, 10, 0), (10, 10, 0), (10, 0, 0), (0, 0, 0)]
+holes = [[(2, 2, 0), (2, 4, 0), (4, 4, 0), (4, 2, 0), (2, 2, 0)]]
+alg = sg.Delaunay2D(shell=shell, holes=holes)
+
+# %%
+# Generate the mesh.
 
-delaunay2d = sg.Delaunay2D(polygon_with_hole)
-delaunay2d.mesh.plot(show_edges=True, color="white", cpos="xy")
+mesh = alg.mesh
+mesh.plot(show_edges=True, color="white", cpos="xy")

pyproject.toml

@@ -3,7 +3,7 @@ requires = [
   'gmsh<4.12.3',
   'meshio<5.3.6',
   'pygmsh<7.1.18',
-  'pyvista',
+  'pyvista[all]<0.44.2',
   'scooby<0.9.3',
   'setuptools<69.0.4',
   'shapely<2.0.6'
@@ -20,14 +20,23 @@ dependencies = [
   'gmsh<4.12.3',
   'meshio<5.3.6',
   'pygmsh<7.1.18',
-  'pyvista',
+  'pyvista[all]<0.44.2',
   'scooby<0.9.3',
   'shapely<2.0.6'
 ]
 requires-python = '>=3.9'
 
 [project.optional-dependencies]
 test = ['pytest==8.0.0']
+docs = [
+  'myst-parser==4.0.0',
+  'sphinx==8.0.2',
+  'sphinx-book-theme==1.1.3',
+  'sphinx-copybutton==0.5.2',
+  'sphinx-design==0.6.1',
+  'sphinx-gallery==0.17.1',
+  'sphinx-toolbox==3.8.0'
+]
 
 [tool.mypy]
 ignore_missing_imports = true
@@ -78,6 +87,7 @@ force-single-line = true
 [tool.ruff.lint.per-file-ignores]
 "docs/**" = ["INP001"]
 "tests/**" = ["INP001", "S101"]
+"examples/**" = ["D205", "D400", "D415", "INP001"]
 
 [tool.ruff.lint.pyupgrade]
 # Preserve types, even if a file imports `from __future__ import annotations`.