Improve C++ docs

cpp/demo/biharmonic/main.cpp

@@ -145,9 +145,10 @@ using U = typename dolfinx::scalar_value_t<T>;
 
 // Inside the `main` function, we begin by defining a mesh of the
 // domain. As the unit square is a very standard domain, we can use a
-// built-in mesh provided by the {cpp:class}`UnitSquareMesh` factory. In
-// order to create a mesh consisting of 32 x 32 squares with each square
-// divided into two triangles, and the finite element space (specified
+// built-in mesh generator provided by the
+// {cpp:func}`dolfinx::mesh::create_rectangle()` function.
+// In order to create a mesh consisting of 32 x 32 squares with each
+// square divided into two triangles, and the finite element space (specified
 // in the form file) defined relative to this mesh, we do as follows
 
 int main(int argc, char* argv[])

cpp/demo/poisson/main.cpp

@@ -96,14 +96,11 @@ using namespace dolfinx;
 using T = PetscScalar;
 using U = typename dolfinx::scalar_value_t<T>;
 
-// Then follows the definition of the coefficient functions (for $f$ and
-// $g$), which are derived from the {cpp:class}`Expression` class in
-// DOLFINx
-
 // Inside the `main` function, we begin by defining a mesh of the
 // domain. As the unit square is a very standard domain, we can use a
-// built-in mesh provided by the {cpp:class}`UnitSquareMesh` factory. In
-// order to create a mesh consisting of 32 x 32 squares with each square
+// built-in mesh generator provided by the
+// {cpp:func}`dolfinx::mesh::create_rectangle()` function.
+// In order to create a mesh consisting of 32 x 32 squares with each square
 // divided into two triangles, and the finite element space (specified
 // in the form file) defined relative to this mesh, we do as follows:
 
@@ -130,7 +127,7 @@ int main(int argc, char* argv[])
 
     //  Next, we define the variational formulation by initializing the
     //  bilinear and linear forms ($a$, $L$) using the previously
-    //  defined {cpp:class}`FunctionSpace` `V`.  Then we can create the
+    //  defined {cpp:class}`dolfinx::fem::FunctionSpace` `V`.  Then we can create the
     //  source and boundary flux term ($f$, $g$) and attach these to the
     //  linear form.
 
@@ -146,11 +143,11 @@ int main(int argc, char* argv[])
                                          {{"f", f}, {"g", g}}, {}, {}, {});
 
     //  Now, the Dirichlet boundary condition ($u = 0$) can be created
-    //  using the class {cpp:class}`DirichletBC`. A
-    //  {cpp:class}`DirichletBC` takes two arguments: the value of the
-    //  boundary condition, and the part of the boundary on which the
-    //  condition applies. In our example, the value of the boundary
-    //  condition (0) can represented using a {cpp:class}`Function`,
+    //  using the class {cpp:class}`dolfinx::fem::DirichletBC`. A
+    //  {cpp:class}`dolfinx::fem::DirichletBC` takes two arguments:
+    //  the value of the boundary condition, and the part of the boundary
+    //  on which the condition applies. In our example, the value of the boundary
+    //  condition (0) can represented using a {cpp:class}`dolfinx::fem::Function`,
     //  and the Dirichlet boundary is defined by the indices of degrees
     //  of freedom to which the boundary condition applies. The
     //  definition of the Dirichlet boundary condition then looks as
@@ -242,9 +239,10 @@ int main(int argc, char* argv[])
     u->x()->scatter_fwd();
 
     //  The function `u` will be modified during the call to solve. A
-    //  {cpp:class}`Function` can be saved to a file. Here, we output
-    //  the solution to a `VTK` file (specified using the suffix `.pvd`)
-    //  for visualisation in an external program such as Paraview.
+    //  {cpp:class}`dolfinx::fem::Function` can be saved to a file.
+    //  Here, we output the solution to a `VTK` file (specified using
+    //  the suffix `.pvd`) for visualisation in an external program such
+    //  as Paraview.
 
     // Save solution in VTK format
     io::VTKFile file(MPI_COMM_WORLD, "u.pvd", "w");

cpp/demo/poisson/poisson.py

@@ -20,12 +20,12 @@
 
 e = element("Lagrange", "triangle", 1)
 
-# The first argument to :py:class:`FiniteElement` is the finite element
-# family, the second argument specifies the domain, while the third
-# argument specifies the polynomial degree. Thus, in this case, our
-# element `element` consists of first-order, continuous Lagrange basis
-# functions on triangles (or in order words, continuous piecewise linear
-# polynomials on triangles).
+# The first argument to {py:func}`element<basix.ufl.element>`
+# is the finite element family, the second argument specifies
+# the domain, while the third argument specifies the polynomial degree.
+# Thus, in this case, our element `e` consists of first-order,
+# continuous Lagrange basis functions on triangles (or in order words,
+# continuous piecewise linear polynomials on triangles).
 #
 # Next, we use this element to initialize the trial and test functions
 # ($u$ and $v$) and the coefficient functions ($f$ and $g$):

cpp/doc/source/conf.py

@@ -12,6 +12,11 @@
 
 import os
 import sys
+import dolfinx
+import basix
+import ufl
+import datetime
+import ffcx
 
 sys.path.insert(0, os.path.abspath("."))
 
@@ -25,12 +30,14 @@
 # -- Project information -----------------------------------------------------
 
 project = "DOLFINx"
-copyright = "2022, FEniCS Project"
+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 = "0.3.1"
+release = dolfinx.cpp.__version__
 
 
 # -- General configuration ---------------------------------------------------
@@ -40,6 +47,10 @@
 # ones.
 extensions = [
     "sphinx.ext.mathjax",
+    "sphinx_codeautolink",
+    "sphinx.ext.viewcode",
+    "sphinx_codeautolink",
+    "sphinx.ext.intersphinx",
     "myst_parser",
     "breathe",
 ]
@@ -77,9 +88,38 @@
 breathe_projects = {"DOLFINx": "../xml/"}
 breathe_default_project = "DOLFINx"
 breathe_implementation_filename_extensions = [".c", ".cc", ".cpp"]
+breathe_domain_by_extension = {
+    "h": "cpp",
+}
 
 # Tell sphinx what the primary language being documented is.
 primary_domain = "cpp"
 
 # Tell sphinx what the pygments highlight language should be.
 highlight_language = "cpp"
+
+intersphinx_resolve_self = "dolfinx"
+codeautolink_concat_default = True
+
+# Could be reimplemented using packaging.version
+basix_version = "main" if "dev0" in basix.__version__ else "v" + basix.__version__
+ffcx_version = "main" if "dev0" in ffcx.__version__ else "v" + ffcx.__version__
+ufl_version = "main" if "dev0" in ufl.__version__ else ufl.__version__
+
+
+# Note that as of late 2025 pyvista and petsc4py only have docs for the latest
+# releases.
+intersphinx_mapping = {
+    "basix": (
+        f"https://docs.fenicsproject.org/basix/{basix_version}/python",
+        None,
+    ),
+    "ffcx": (
+        f"https://docs.fenicsproject.org/ffcx/{ffcx_version}",
+        None,
+    ),
+    "ufl": (
+        f"https://docs.fenicsproject.org/ufl/{ufl_version}",
+        None,
+    ),
+}