Render Psydac examples as a sphinx-gallery

.github/workflows/documentation.yml

@@ -19,23 +19,39 @@ jobs:
  steps:
  - name: Checkout
  uses: actions/checkout@v3
+
  - name: Set up Python
  uses: actions/setup-python@v4
  with:
  python-version: 3.9
+
  - name: Install non-Python dependencies on Ubuntu
  run: |
- sudo apt update
- sudo apt install graphviz
- - name: Install Python dependencies
+ sudo apt-get update
+ sudo apt-get install gfortran
+ sudo apt-get install openmpi-bin libopenmpi-dev
+ sudo apt-get install libhdf5-openmpi-dev
+ sudo apt-get install graphviz
+
+ - name: Install Python dependencies on Ubuntu
  run: |
+ export CC="mpicc" HDF5_MPI="ON"
+ export HDF5_DIR="/usr/lib/x86_64-linux-gnu/hdf5/openmpi"
+ python -m pip install -r requirements.txt
+ python -m pip install -r requirements_extra.txt --no-build-isolation
  python -m pip install -r docs_requirements.txt
+
+ - name: Install Psydac
+ run: |
+ python -m pip install .
+ python -m pip freeze
+
  - name: Make the sphinx doc
  run: |
  rm -rf docs/source/modules/STUBDIR
- make -C docs clean
- make -C docs html
+ make -C docs clean html
  python docs/update_links.py
+
  - name: Setup Pages
  uses: actions/configure-pages@v3
  - name: Upload artifact

.gitignore

@@ -19,6 +19,9 @@ usr
 doc/_static
 doc/_build
 doc/api-python
+docs/source/modules/STUBDIR
+docs/source/auto_examples
+docs/source/sg_execution_times.rst
 
 psydac/core/bsp-f2py*
 psydac/core/bspmodule.c

docs/source/conf.py

@@ -35,14 +35,15 @@ def fixed_init(self, app):
  pkg_meta = tomli.load(pyproject)['project']
 
 project = str(pkg_meta['name'])
-copyright = '2018-2023, Psydac Developers'
+copyright = '2018-2024, Psydac Developers'
 author = str(pkg_meta['authors'][0]['name'])
 release = str(pkg_meta['version'])
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
+'sphinx_gallery.gen_gallery',
 'sphinx.ext.inheritance_diagram',
 'numpydoc',
 'sphinx.ext.viewcode',
@@ -51,9 +52,16 @@ def fixed_init(self, app):
 'sphinx.ext.autosummary',
 'sphinx.ext.githubpages',
 'sphinx_math_dollar',
-'sphinx.ext.mathjax',
+'sphinx.ext.mathjax'
 ]
 
+# -- Options for sphinx_gallery ----------------------------------------------
+# 'ignore_pattern': r'maxwell_|poisson_|sample_|test_|visualize_'
+sphinx_gallery_conf = {
+ 'examples_dirs': '../../examples/notebooks', # path to your example scripts
+ 'gallery_dirs': 'auto_examples' # path to where to save gallery generated output
+}
+
 from docutils.nodes import FixedTextElement, literal,math
 from docutils.nodes import comment, doctest_block, image, literal_block, math_block, paragraph, pending, raw, rubric, substitution_definition, target
 math_dollar_node_blacklist = (literal,math,doctest_block, image, literal_block, math_block, pending, raw,rubric, substitution_definition,target)
@@ -91,4 +99,4 @@ def fixed_init(self, app):
  fontsize="12")
 
 inheritance_node_attrs = dict(shape='ellipse', fontsize="12", height=0.65,
- color='maroon4', style='filled')
+ color='maroon4', style='filled')

docs/source/examples.rst

@@ -1,6 +1,4 @@
-Examples
-========
+.. toctree::
+ :maxdepth: 1
 
-+------------------------------------------------------------------------------------------------------------------------+
-| Here you will find examples of how to use PSYDAC and explanations thereof as well as links to notebooks in the future. |
-+------------------------------------------------------------------------------------------------------------------------+
+ auto_examples/index.rst

docs_requirements.txt

@@ -1,5 +1,7 @@
-sphinx
-pydata_sphinx_theme
+matplotlib
 numpydoc
-tomli
+pydata_sphinx_theme
+sphinx
+sphinx-gallery
 sphinx-math-dollar
+tomli

examples/notebooks/README.rst

@@ -0,0 +1,6 @@
+Examples
+========
+
++------------------------------------------------------------------------------------------------------------------------+
+| Here you will find examples of how to use PSYDAC and explanations thereof as well as links to notebooks in the future. |
++------------------------------------------------------------------------------------------------------------------------+