From a6f4e562f1c0193c4b7dcd1cc983b0becb30f9c4 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Thu, 21 May 2026 16:38:29 +0200 Subject: [PATCH 01/14] Try doc build with pydata-sphinx-theme --- cpp/doc/source/conf.py | 8 +++----- python/doc/source/conf.py | 9 ++++----- python/pyproject.toml | 2 +- 3 files changed, 8 insertions(+), 11 deletions(-) diff --git a/cpp/doc/source/conf.py b/cpp/doc/source/conf.py index 0b5fa5e2f40..9fe33466050 100644 --- a/cpp/doc/source/conf.py +++ b/cpp/doc/source/conf.py @@ -36,10 +36,8 @@ copyright = f"{date.year}, FEniCS Project" author = "FEniCS Project" -# TODO: automate version tagging? -# The full version, including alpha/beta/rc tags -release = dolfinx.cpp.__version__ - +version = dolfinx.cpp.__version__ +release = version # -- General configuration --------------------------------------------------- @@ -73,7 +71,7 @@ # # html_theme = 'alabaster' # html_theme = "nature" -html_theme = "sphinx_rtd_theme" +html_theme = "pydata_sphinx_theme" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/python/doc/source/conf.py b/python/doc/source/conf.py index 795eaa713b0..92e0be6f66f 100644 --- a/python/doc/source/conf.py +++ b/python/doc/source/conf.py @@ -3,6 +3,7 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import datetime +import importlib.metadata import os import sys @@ -12,7 +13,6 @@ import packaging import basix -import dolfinx import ffcx import ufl @@ -74,9 +74,8 @@ # built documents. # # The short X.Y version. -version = dolfinx.__version__ -# The full version, including alpha/beta/rc tags. -release = dolfinx.__version__ +version = importlib.metadata.version("fenics-dolfinx") +release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -102,7 +101,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "sphinx_rtd_theme" +html_theme = "pydata_sphinx_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/python/pyproject.toml b/python/pyproject.toml index 304fff94481..a932ff8951c 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -44,7 +44,7 @@ docs = [ "packaging", "pyyaml", "sphinx", - "sphinx_rtd_theme", + "pydata-sphinx-theme", "sphinx_codeautolink[ipython]", "sphinxcontrib-bibtex", "fenics-dolfinx[demo]", From 60c57a2c55a1d46fb3c6ef4b5c507bf540a928d8 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Thu, 21 May 2026 22:27:06 +0200 Subject: [PATCH 02/14] Fix --- cpp/doc/source/conf.py | 2 +- cpp/doc/source/demo.rst | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/cpp/doc/source/conf.py b/cpp/doc/source/conf.py index 9fe33466050..294f05ee139 100644 --- a/cpp/doc/source/conf.py +++ b/cpp/doc/source/conf.py @@ -30,7 +30,7 @@ # -- Project information ----------------------------------------------------- -project = "DOLFINx" +project = "DOLFINx C++" now = datetime.datetime.now() date = now.date() copyright = f"{date.year}, FEniCS Project" diff --git a/cpp/doc/source/demo.rst b/cpp/doc/source/demo.rst index 69eaee27a11..d666e8fb9eb 100644 --- a/cpp/doc/source/demo.rst +++ b/cpp/doc/source/demo.rst @@ -35,3 +35,4 @@ Advanced :maxdepth: 1 demos/demo_custom_kernel.md + demos/demo_codim_0_assembly.md From 3b666bb3c40c03ccf9ea9ec534bbfb678d67a8d6 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Thu, 21 May 2026 22:30:05 +0200 Subject: [PATCH 03/14] Fix --- python/doc/source/demos.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/doc/source/demos.rst b/python/doc/source/demos.rst index 62009fa0c33..ccb3db97efe 100644 --- a/python/doc/source/demos.rst +++ b/python/doc/source/demos.rst @@ -86,7 +86,7 @@ User-defined and advanced finite elements .. toctree:: :maxdepth: 1 - demos/demo_lagrange_variants.md + demos/demo_lagrange-variants.md demos/demo_tnt-elements.md From ce90849a008c2512d48880279416df1a642a46f2 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Thu, 21 May 2026 22:31:00 +0200 Subject: [PATCH 04/14] Add Python to title --- python/doc/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/python/doc/source/conf.py b/python/doc/source/conf.py index 92e0be6f66f..1a88de83e49 100644 --- a/python/doc/source/conf.py +++ b/python/doc/source/conf.py @@ -63,7 +63,7 @@ master_doc = "index" # General information about the project. -project = "DOLFINx" +project = "DOLFINx Python" now = datetime.datetime.now() date = now.date() copyright = f"{date.year}, FEniCS Project" From efd8fb0225d5712d9dc5ffed76a3875e0ae98670 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Thu, 21 May 2026 22:54:29 +0200 Subject: [PATCH 05/14] Nicer looking titles --- cpp/doc/source/conf.py | 1 + python/doc/source/conf.py | 1 + 2 files changed, 2 insertions(+) diff --git a/cpp/doc/source/conf.py b/cpp/doc/source/conf.py index 294f05ee139..713c34b3032 100644 --- a/cpp/doc/source/conf.py +++ b/cpp/doc/source/conf.py @@ -72,6 +72,7 @@ # html_theme = 'alabaster' # html_theme = "nature" html_theme = "pydata_sphinx_theme" +html_title = f"DOLFINx C++ {release}" # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/python/doc/source/conf.py b/python/doc/source/conf.py index 1a88de83e49..8be3d5dbabe 100644 --- a/python/doc/source/conf.py +++ b/python/doc/source/conf.py @@ -102,6 +102,7 @@ # a list of builtin themes. # html_theme = "pydata_sphinx_theme" +html_title = f"DOLFINx Python {release}" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the From d3b2104c26b0da5db3e4827828f2e06483069798 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Thu, 21 May 2026 22:56:30 +0200 Subject: [PATCH 06/14] Clearer opening language on index --- cpp/doc/source/index.rst | 1 - python/doc/source/index.rst | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/cpp/doc/source/index.rst b/cpp/doc/source/index.rst index 7b57a5d06c1..369676822bc 100644 --- a/cpp/doc/source/index.rst +++ b/cpp/doc/source/index.rst @@ -1,4 +1,3 @@ -========================= DOLFINx C++ documentation ========================= diff --git a/python/doc/source/index.rst b/python/doc/source/index.rst index b34838a94c3..3b55d8b2341 100644 --- a/python/doc/source/index.rst +++ b/python/doc/source/index.rst @@ -1,5 +1,5 @@ -DOLFINx documentation -===================== +DOLFINx Python documentation +============================ DOLFINx is the next generation problem solving interface of the `FEniCS Project `_. It is developed on `GitHub From aeef10827cc5c2afbfaeaf7eedbb9d633efcff74 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Tue, 26 May 2026 12:48:56 +0200 Subject: [PATCH 07/14] Tweak. --- cpp/doc/Doxyfile | 2 +- python/doc/source/api.rst | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/cpp/doc/Doxyfile b/cpp/doc/Doxyfile index a893aedd880..916c8640942 100644 --- a/cpp/doc/Doxyfile +++ b/cpp/doc/Doxyfile @@ -54,7 +54,7 @@ PROJECT_NUMBER = $(DOLFINX_VERSION) # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = "DOLFINx C++ interface" +PROJECT_BRIEF = "DOLFINx C++" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 diff --git a/python/doc/source/api.rst b/python/doc/source/api.rst index 2768411f127..b7b09f78f47 100644 --- a/python/doc/source/api.rst +++ b/python/doc/source/api.rst @@ -44,6 +44,7 @@ application-level use. dolfinx.cpp.common dolfinx.cpp.fem dolfinx.cpp.fem.petsc + dolfinx.cpp.fem.superlu_dist dolfinx.cpp.geometry dolfinx.cpp.graph dolfinx.cpp.io From 8cb6ef0519e489da3b69d3bb93180a7616d72d5b Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Tue, 26 May 2026 13:17:48 +0200 Subject: [PATCH 08/14] Remove --- python/doc/source/api.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/python/doc/source/api.rst b/python/doc/source/api.rst index b7b09f78f47..2768411f127 100644 --- a/python/doc/source/api.rst +++ b/python/doc/source/api.rst @@ -44,7 +44,6 @@ application-level use. dolfinx.cpp.common dolfinx.cpp.fem dolfinx.cpp.fem.petsc - dolfinx.cpp.fem.superlu_dist dolfinx.cpp.geometry dolfinx.cpp.graph dolfinx.cpp.io From c8147a90ffed33c096aeb9f65325d593a0bcc973 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Wed, 27 May 2026 13:55:10 +0200 Subject: [PATCH 09/14] Remove Makefile, improve C++ doc build instructions --- cpp/doc/Makefile | 20 -------------------- cpp/doc/README.md | 19 ++++++++++++------- 2 files changed, 12 insertions(+), 27 deletions(-) delete mode 100644 cpp/doc/Makefile diff --git a/cpp/doc/Makefile b/cpp/doc/Makefile deleted file mode 100644 index 38a74029528..00000000000 --- a/cpp/doc/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -# SPHINXOPTS = -W -SPHINXBUILD = sphinx-build -SPHINXPROJ = FEniCSProject -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/cpp/doc/README.md b/cpp/doc/README.md index 81770b5b853..537b06805e3 100644 --- a/cpp/doc/README.md +++ b/cpp/doc/README.md @@ -1,24 +1,29 @@ # DOLFINx C++ interface documentation The C++ API documentation is generated from the source code using -[Doxygen](https://www.doxygen.nl/), and the Doxygen output is curated -and rendered using reStructured text with -[Sphinx](https://www.sphinx-doc.org/) and +[Doxygen](https://www.doxygen.nl/), and the Doxygen output is curated and +rendered using reStructured text with [Sphinx](https://www.sphinx-doc.org/) and [Breathe](https://breathe.readthedocs.io/). ## Requirements +For the basic C++ documentation: + - [Doxygen](https://www.doxygen.nl/) -- [Sphinx](https://www.sphinx-doc.org/) -- [Breathe](https://breathe.readthedocs.io/) +And then for the nicer-looking Sphinx documentation, Python with: + +- [sphinx](https://www.sphinx-doc.org/) +- [breathe](https://breathe.readthedocs.io/) +- [pydata-sphinx-theme](https://pydata-sphinx-theme.readthedocs.io/en/stable/) +- [myst-parser](https://myst-parser.readthedocs.io/en/latest/) ## Building ```bash -> doxygen Doxyfile -> make html +doxygen Doxyfile +python -m sphinx -W -b html source/ build/html/ ``` Sphinx/Breathe documentation is in `build/html`and the Doxygen generated From e928f9d7261a4d483fae122bcb3fba2f7f330723 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Wed, 27 May 2026 14:17:56 +0200 Subject: [PATCH 10/14] Consistent demo naming --- ...emo_half_loaded_waveguide.py => demo_half-loaded-waveguide.py} | 0 .../demo/{demo_lagrange_variants.py => demo_lagrange-variants.py} | 0 .../demo/{demo_matrix_free_petsc.py => demo_matrix-free-petsc.py} | 0 .../{demo_poisson_matrix_free.py => demo_poisson-matrix-free.py} | 0 ...ndary_conditions.py => demo_scattering-boundary-conditions.py} | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename python/demo/{demo_half_loaded_waveguide.py => demo_half-loaded-waveguide.py} (100%) rename python/demo/{demo_lagrange_variants.py => demo_lagrange-variants.py} (100%) rename python/demo/{demo_matrix_free_petsc.py => demo_matrix-free-petsc.py} (100%) rename python/demo/{demo_poisson_matrix_free.py => demo_poisson-matrix-free.py} (100%) rename python/demo/{demo_scattering_boundary_conditions.py => demo_scattering-boundary-conditions.py} (100%) diff --git a/python/demo/demo_half_loaded_waveguide.py b/python/demo/demo_half-loaded-waveguide.py similarity index 100% rename from python/demo/demo_half_loaded_waveguide.py rename to python/demo/demo_half-loaded-waveguide.py diff --git a/python/demo/demo_lagrange_variants.py b/python/demo/demo_lagrange-variants.py similarity index 100% rename from python/demo/demo_lagrange_variants.py rename to python/demo/demo_lagrange-variants.py diff --git a/python/demo/demo_matrix_free_petsc.py b/python/demo/demo_matrix-free-petsc.py similarity index 100% rename from python/demo/demo_matrix_free_petsc.py rename to python/demo/demo_matrix-free-petsc.py diff --git a/python/demo/demo_poisson_matrix_free.py b/python/demo/demo_poisson-matrix-free.py similarity index 100% rename from python/demo/demo_poisson_matrix_free.py rename to python/demo/demo_poisson-matrix-free.py diff --git a/python/demo/demo_scattering_boundary_conditions.py b/python/demo/demo_scattering-boundary-conditions.py similarity index 100% rename from python/demo/demo_scattering_boundary_conditions.py rename to python/demo/demo_scattering-boundary-conditions.py From 843b5dc0e28e1c21d071dbbb5077c7fa6cdbf323 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Wed, 27 May 2026 14:24:49 +0200 Subject: [PATCH 11/14] More tweaking demo names --- python/doc/source/demos.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/python/doc/source/demos.rst b/python/doc/source/demos.rst index ccb3db97efe..88b6aac8c22 100644 --- a/python/doc/source/demos.rst +++ b/python/doc/source/demos.rst @@ -15,9 +15,9 @@ PDEs (introductory) demos/demo_poisson.md demos/demo_helmholtz.md - demos/demo_scattering_boundary_conditions.md + demos/demo_scattering-boundary-conditions.md demos/demo_pml.md - demos/demo_half_loaded_waveguide.md + demos/demo_half-loaded-waveguide.md demos/demo_axis.md PDEs (advanced) @@ -34,11 +34,11 @@ PDEs (advanced) demos/demo_static-condensation.md demos/demo_biharmonic.md demos/demo_types.md - demos/demo_poisson_matrix_free.md + demos/demo_poisson-matrix-free.md demos/demo_pyamg.md demos/demo_hdg.md demos/demo_mixed-topology.md - demos/demo_matrix_free_petsc.md + demos/demo_matrix-free-petsc.md @@ -116,11 +116,11 @@ List of all demos demos/demo_pyvista.md demos/demo_interpolation-io.md demos/demo_types.md - demos/demo_lagrange_variants.md + demos/demo_lagrange-variants.md demos/demo_tnt-elements.md - demos/demo_scattering_boundary_conditions.md + demos/demo_scattering-boundary-conditions.md demos/demo_pml.md - demos/demo_half_loaded_waveguide.md + demos/demo_half-loaded-waveguide.md demos/demo_axis.md demos/demo_navier-stokes.md demos/demo_mixed-poisson.md From 63cb2e09b9406a16051dff9e1fbed18a9485a58e Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Wed, 27 May 2026 14:32:49 +0200 Subject: [PATCH 12/14] Fix links --- python/demo/demo_half-loaded-waveguide.py | 4 ++-- python/demo/demo_lagrange-variants.py | 4 ++-- python/demo/demo_matrix-free-petsc.py | 2 +- python/demo/demo_pml.py | 2 +- python/demo/demo_poisson-matrix-free.py | 4 ++-- python/demo/demo_scattering-boundary-conditions.py | 4 ++-- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/python/demo/demo_half-loaded-waveguide.py b/python/demo/demo_half-loaded-waveguide.py index e6014219eae..f8270c45917 100644 --- a/python/demo/demo_half-loaded-waveguide.py +++ b/python/demo/demo_half-loaded-waveguide.py @@ -19,8 +19,8 @@ # # ```{admonition} Download sources # :class: download -# * {download}`Python script <./demo_half_loaded_waveguide.py>` -# * {download}`Jupyter notebook <./demo_half_loaded_waveguide.ipynb>` +# * {download}`Python script <./demo_half-loaded-waveguide.py>` +# * {download}`Jupyter notebook <./demo_half-loaded-waveguide.ipynb>` # ``` # # The demo shows how to: diff --git a/python/demo/demo_lagrange-variants.py b/python/demo/demo_lagrange-variants.py index 135f12a8637..2f7687fa32b 100644 --- a/python/demo/demo_lagrange-variants.py +++ b/python/demo/demo_lagrange-variants.py @@ -12,8 +12,8 @@ # # ```{admonition} Download sources # :class: download -# * {download}`Python script <./demo_lagrange_variants.py>` -# * {download}`Jupyter notebook <./demo_lagrange_variants.ipynb>` +# * {download}`Python script <./demo_lagrange-variants.py>` +# * {download}`Jupyter notebook <./demo_lagrange-variants.ipynb>` # ``` # This demo illustrates how to: # diff --git a/python/demo/demo_matrix-free-petsc.py b/python/demo/demo_matrix-free-petsc.py index 41593814c72..15dbe5612e2 100644 --- a/python/demo/demo_matrix-free-petsc.py +++ b/python/demo/demo_matrix-free-petsc.py @@ -13,7 +13,7 @@ # Author: Jørgen S. Dokken # # This demo can be downloaded as a single Python file -# {download}`demo_matrix_free_petsc.py`. +# {download}`demo_matrix-free-petsc.py`. # In this demo, we will demonstrate how to set up a matrix-free # solver using PETSc. # We will start by defining our variational problem, and then in turn diff --git a/python/demo/demo_pml.py b/python/demo/demo_pml.py index c5634bf72d9..a9d6026e6a5 100644 --- a/python/demo/demo_pml.py +++ b/python/demo/demo_pml.py @@ -719,7 +719,7 @@ def create_eps_mu( ) # We calculate the numerical efficiencies in the same way as done in -# [Electromagnetic scattering demo](./demo_scattering_boundary_conditions), +# [Electromagnetic scattering demo](./demo_scattering-boundary-conditions), # with the only difference that now the scattering efficiency needs to be # calculated over an inner facet, and therefore it requires a slightly # different approach: diff --git a/python/demo/demo_poisson-matrix-free.py b/python/demo/demo_poisson-matrix-free.py index 3d1fd71b1d6..f02733be032 100644 --- a/python/demo/demo_poisson-matrix-free.py +++ b/python/demo/demo_poisson-matrix-free.py @@ -16,8 +16,8 @@ # # ```{admonition} Download sources # :class: download -# * {download}`Python script <./demo_poisson_matrix_free.py>` -# * {download}`Jupyter notebook <./demo_poisson_matrix_free.ipynb>` +# * {download}`Python script <./demo_poisson-matrix-free.py>` +# * {download}`Jupyter notebook <./demo_poisson-matrix-free.ipynb>` # ``` # This demo illustrates how to solve the Poisson equation using a # matrix-free conjugate gradient (CG) solver. In particular, it diff --git a/python/demo/demo_scattering-boundary-conditions.py b/python/demo/demo_scattering-boundary-conditions.py index 3c40b835742..e92f547b7da 100644 --- a/python/demo/demo_scattering-boundary-conditions.py +++ b/python/demo/demo_scattering-boundary-conditions.py @@ -21,9 +21,9 @@ # ```{admonition} Download sources # :class: download # * {download}`Python script -# <./demo_scattering_boundary_conditions.py>` +# <./demo_scattering-boundary-conditions.py>` # * {download}`Jupyter notebook -# <./demo_scattering_boundary_conditions.ipynb>` +# <./demo_scattering-boundary-conditions.ipynb>` # ``` # # This demo illustrates how to: From 6e767efb0106e9d9c19b4bf6c1e8e5e395f12bd1 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Wed, 27 May 2026 14:33:12 +0200 Subject: [PATCH 13/14] Doesn't build without warnings --- cpp/doc/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cpp/doc/README.md b/cpp/doc/README.md index 537b06805e3..ce7fc6a2770 100644 --- a/cpp/doc/README.md +++ b/cpp/doc/README.md @@ -23,7 +23,7 @@ And then for the nicer-looking Sphinx documentation, Python with: ```bash doxygen Doxyfile -python -m sphinx -W -b html source/ build/html/ +python -m sphinx -b html source/ build/html/ ``` Sphinx/Breathe documentation is in `build/html`and the Doxygen generated From d45a51346a7b0988b1a80b7d8553ece24b61d1f6 Mon Sep 17 00:00:00 2001 From: "Jack S. Hale" Date: Wed, 27 May 2026 14:34:59 +0200 Subject: [PATCH 14/14] Fix C++ doc build now Makefile gone --- .github/workflows/ccpp.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ccpp.yml b/.github/workflows/ccpp.yml index 80e0782c470..94b1e4e7441 100644 --- a/.github/workflows/ccpp.yml +++ b/.github/workflows/ccpp.yml @@ -321,7 +321,7 @@ jobs: echo $DOLFINX_VERSION cd cpp/doc doxygen Doxyfile - make html + python -m sphinx -b html source/ build/html - name: Upload C++ Doxygen documentation artifact uses: actions/upload-artifact@v7 with: