Render Psydac examples as a sphinx-gallery

[kvrigor]

I'm testing Sphinx-Gallery to render some Python scripts under psydac/examples/*. This gallery is the same one that Scikit-learn uses. First the doc deployment pipeline needs to be functional; once it works we can decide which example scripts to showcase.

When building the docs locally, I get an error TypeError: isinstance() arg 2 must be a type or tuple of types:

~/psydac
$ (psydac-python3.9-env) cd docs

~/psydac/docs
$ (psydac-python3.9-env) make clean && make html
Removing everything under 'build'...
Running Sphinx v7.2.6
making output directory... done
Using Sphinx-Gallery to convert rst text blocks to markdown for .ipynb files.
[autosummary] generating autosummary for: auto_examples/index.rst, auto_examples/plot_poisson_1d.rst, auto_examples/plot_poisson_non_periodic.rst, auto_examples/sg_execution_times.rst, examples.rst, index.rst, maintenance.rst, modules.rst, modules/STUBDIR/psydac.api.ast.basic.rst, modules/STUBDIR/psydac.api.ast.evaluation.rst, ..., modules/ddm.rst, modules/feec.multipatch.rst, modules/feec.rst, modules/fem.rst, modules/linalg.kernels.rst, modules/linalg.rst, modules/mapping.rst, modules/polar.rst, modules/utilities.rst, sg_execution_times.rst
generating gallery...
WARNING: g gallery for auto_examples... [ 50%] plot_poisson_non_periodic.py
../../examples/notebooks/plot_poisson_non_periodic.py unexpectedly failed to execute correctly:

    Traceback (most recent call last):
      File "psydac/examples/notebooks/plot_poisson_non_periodic.py", line 107, in <module>
        Omega_h = discretize(Omega, ncells=ncells, periodic=periodic)
      File "psydac/psydac/api/discretization.py", line 480, in discretize
        if isinstance(a, (sym_BasicForm, sym_GltExpr, sym_Expr)):
    TypeError: isinstance() arg 2 must be a type or tuple of types

WARNING: g gallery for auto_examples... [100%] plot_poisson_1d.py
psydac/examples/notebooks/plot_poisson_1d.py unexpectedly failed to execute correctly:

    Traceback (most recent call last):
      File "psydac/examples/notebooks/plot_poisson_1d.py", line 247, in <module>
        space = SplineSpace(p, grid=grid, periodic=model.periodic)
      File "psydac/psydac/fem/splines.py", line 143, in __init__
        self._vector_space = StencilVectorSpace( cart )
      File "psydac/psydac/linalg/stencil.py", line 141, in __init__
        self._mpi_type      = find_mpi_type(dtype)
      File "psydac/psydac/ddm/cart.py", line 34, in find_mpi_type
        if isinstance( dtype, MPI.Datatype ):
    TypeError: isinstance() arg 2 must be a type or tuple of types


computation time summary:
    - psydac/examples/notebooks/plot_poisson_non_periodic.py:   1.37 sec   0.0 MB
    - psydac/examples/notebooks/plot_poisson_1d.py:             0.31 sec   0.0 MB
The default value for `navigation_with_keys` will change to `False` in the next release. If you wish to preserve the old behavior for your site, set `navigation_with_keys=True` in the `html_theme_options` dict in your `conf.py` file. Be aware that `navigation_with_keys = True` has negative accessibility implications: https://github.com/pydata/pydata-sphinx-theme/issues/1492
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 102 source files that are out of date
updating environment: [new config] 102 added, 0 changed, 0 removed
[Ctrl+C]
Interrupted!
make: *** [Makefile:20: html] Interrupt

I get the same error for python3.10 and python3.11. Oddly enough I cannot replicate this error either in interactive shell or when running a script. I suspect this issue is related to sphinx-build itself.

@yguclu Could you help to trigger the build_docs workflow? I would like to verify whether this error is an artifact of my dev environment or not.

[kvrigor]

I would like to verify whether this error is an artifact of my dev environment or not.

Most recent build_docs run can replicate the issue. The isinstance() error may be related to sphinx#9505; I need to dig further.

[kvrigor]

Error fixed has been fixed in 46f9e8b, and its corresponding sphinx-build output is attached here. Here are the commands to run this demo locally:

wget https://github.com/pyccel/psydac/files/15009146/build.tar.gz
tar xf build.tar.gz -C .
open build/html/index.html

Next things TODO:

• [ ] Sphinx extension options and logic in docs/source/conf.py needs better documentation
• [ ] Create proper examples to be showcased in the gallery