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: 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/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..ce7fc6a2770 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 -b html source/ build/html/ ``` Sphinx/Breathe documentation is in `build/html`and the Doxygen generated diff --git a/cpp/doc/source/conf.py b/cpp/doc/source/conf.py index 0b5fa5e2f40..713c34b3032 100644 --- a/cpp/doc/source/conf.py +++ b/cpp/doc/source/conf.py @@ -30,16 +30,14 @@ # -- Project information ----------------------------------------------------- -project = "DOLFINx" +project = "DOLFINx C++" now = datetime.datetime.now() date = now.date() 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,8 @@ # # html_theme = 'alabaster' # html_theme = "nature" -html_theme = "sphinx_rtd_theme" +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/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 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/demo/demo_half_loaded_waveguide.py b/python/demo/demo_half-loaded-waveguide.py similarity index 99% rename from python/demo/demo_half_loaded_waveguide.py rename to 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 similarity index 98% rename from python/demo/demo_lagrange_variants.py rename to 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 similarity index 99% rename from python/demo/demo_matrix_free_petsc.py rename to 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 similarity index 98% rename from python/demo/demo_poisson_matrix_free.py rename to 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 similarity index 99% rename from python/demo/demo_scattering_boundary_conditions.py rename to 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: diff --git a/python/doc/source/conf.py b/python/doc/source/conf.py index 795eaa713b0..8be3d5dbabe 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 @@ -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" @@ -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,8 @@ # 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" +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 diff --git a/python/doc/source/demos.rst b/python/doc/source/demos.rst index 62009fa0c33..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 @@ -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 @@ -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 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 diff --git a/python/pyproject.toml b/python/pyproject.toml index 3d051fa13cf..95454ca341a 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]",