[Doc] Add C++ examples to sphinx-gallery

doc/SConscript

@@ -119,15 +119,25 @@ if localenv['sphinx_docs']:
 
     # RecursiveInstall knows to copy modified files, unlike Copy
     copy_sphinx = localenv.RecursiveInstall("#build/doc/sphinx", "sphinx")
-    copy_samples = localenv.RecursiveInstall("#build/doc/samples", "#samples")
+    copy_python_samples = localenv.RecursiveInstall("#build/doc/samples/python",
+                                                    "#samples/python")
 
     sphinxdocs = build(localenv.Command('build/doc/sphinx/html/index.html',
         'sphinx/conf.py', build_sphinx))
     env.Alias('sphinx', sphinxdocs)
     env.Depends(sphinxdocs, copy_sphinx)
-    env.Depends(sphinxdocs, copy_samples)
+    env.Depends(sphinxdocs, copy_python_samples)
     env.Depends(sphinxdocs, env['python_module'])
 
+    # Gather all C++ samples into a single directory so they can be presented a single
+    # sub-gallery by sphinx-gallery
+    cxxfiles = (Glob("#samples/cxx/*/*.cpp") + Glob("#samples/cxx/*/*.h")
+                + Glob("#samples/cxx/*.rst"))
+    for cxxfile in cxxfiles:
+        env.Depends(sphinxdocs,
+                    localenv.Command(f"#build/doc/samples/cxx/{cxxfile.name}", cxxfile,
+                                     Copy("$TARGET", "$SOURCE")))
+
     # Create a list of MATLAB classes to document. This uses the NamedTuple
     # structure defined at the top of the file. The @Data and @Utilities
     # classes are fake classes for the purposes of documentation only. Each

doc/sphinx/conf.py

@@ -49,12 +49,16 @@ extensions = [
 
 sphinx_gallery_conf = {
     'filename_pattern': '\.py',
+    'example_extensions': {'.py', '.cpp', '.h'},
+    "filetype_parsers": {'.h': 'C++'},
     'image_srcset': ["2x"],
     'examples_dirs': [
        '../samples/python/',
+       '../samples/cxx/',
     ],
     'gallery_dirs': [
        'examples/python',
+       'examples/cxx',
     ],
     'reference_url': {
         'cantera': None,  # 'None' means the locally-documented module
@@ -115,6 +119,7 @@ tags_page_title = "Tag"
 tags_page_header = "Examples with this tag:"
 tags_badge_colors = {
     "Python": "secondary",
+    "C++": "secondary",
 }
 
 autodoc_default_options = {

doc/sphinx/index.rst

@@ -16,5 +16,6 @@ format.
    matlab/index
 
    examples/python/index
+   examples/cxx/index
 
    _tags/tagsindex

samples/cxx/LiC6_electrode/LiC6_electrode.cpp

@@ -1,13 +1,12 @@
-/*!
- * @file LiC6_electrode.cpp
- *
- * LiC6 Electrode
+/*
+ * LiC6 electrode
+ * ==============
  *
  * Calculate the open-circuit potential of an LiC6 electrode and activity
  * coefficients of each species as a function of the mole fraction of
  * intercalated lithium.
  *
- * Keywords: thermodynamics, electrochemistry, battery
+ * .. tags:: C++, thermodynamics, electrochemistry, battery
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/README.rst

@@ -0,0 +1,2 @@
+C++ Examples
+============

samples/cxx/bvp/BoundaryValueProblem.h

@@ -1,7 +1,11 @@
-/**
- *  @file BoundaryValueProblem.h
- *  Simplified interface to the capabilities provided by %Cantera to
- *  solve boundary value problems.
+/*
+ * Class `BoundaryValueProblem`
+ * ============================
+ *
+ * Simplified interface to the capabilities provided by Cantera to solve boundary value
+ * problems. See :doc:`blasius.cpp <blasius>` for an example using this class.
+ *
+ * .. tags:: C++, user-defined model
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/bvp/blasius.cpp

@@ -1,14 +1,13 @@
-/*!
- * @file blasius.cpp
+/*
+ * Blasius BVP solver
+ * ==================
  *
- * Blasius BVP Solver
+ * This example solves the Blasius boundary value problem for the velocity profile of a
+ * laminar boundary layer over a flat plate. It uses class ``BoundaryValueProblem``,
+ * defined in :doc:`BoundaryValueProblem.h <BoundaryValueProblem>`, which provides a
+ * simplified interface to the boundary value problem capabilities of Cantera.
  *
- * This example solves the Blasius boundary value problem for the velocity
- * profile of a laminar boundary layer over a flat plate. It defines class
- * BoundaryValueProblem, which provides a simplified interface to the boundary
- * value problem capabilities of Cantera.
- *
- * Keywords: user-defined model
+ * .. tags:: C++, user-defined model
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
@@ -18,18 +17,22 @@
 
 using Cantera::npos;
 
-/**
+/* %%
  * This class solves the Blasius boundary value problem on the domain (0,L):
- * @f[
- *             \frac{d\zeta}{dz} = u.
- * @f]
- * @f[
- *             \frac{d^2u}{dz^2} + 0.5\zeta \frac{du}{dz} = 0.
- * @f]
+ *
+ * .. math::
+ *             \frac{d\zeta}{dz} = u
+ *
+ *             \frac{d^2u}{dz^2} + 0.5\zeta \frac{du}{dz} = 0
+ *
  * with boundary conditions
- * @f[
- * \zeta(0) = 0, u(0) = 0, u(L) = 1.
- * @f]
+ *
+ * .. math::
+ *
+ *     \zeta(0) & = 0 \\
+ *         u(0) & = 0 \\
+ *         u(L) & = 1
+ *
  * Note that this is formulated as a system of two equations, with maximum
  * order of 2, rather than as a single third-order boundary value problem.
  * For reasons having to do with the band structure of the Jacobian, no

samples/cxx/combustor/combustor.cpp

@@ -1,16 +1,15 @@
-/*!
- * @file combustor.cpp
+/*
+ * Adiabatic combustor
+ * ===================
  *
- * Adiabatic Combustor
- *
- * Two separate stream - one pure methane and the other air, both at 300 K
+ * Two separate streams - one pure methane and the other air, both at 300 K
  * and 1 atm flow into an adiabatic combustor where they mix. We are interested
  * in the steady-state burning solution. Since at 300 K no reaction will occur
  * between methane and air, we need to use an 'igniter' to initiate the
  * chemistry. A simple igniter is a pulsed flow of atomic hydrogen. After the
  * igniter is turned off, the system approaches the steady burning solution.
  *
- * Keywords: combustion, reactor network, well-stirred reactor
+ * .. tags:: C++, combustion, reactor network, well-stirred reactor
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/custom/custom.cpp

@@ -1,13 +1,12 @@
-/*!
- * @file custom.cpp
- *
- * Custom Reactor
+/*
+ * Custom reactor
+ * ==============
  *
  * Solve a closed-system constant pressure ignition problem where the governing
  * equations are custom-implemented, using Cantera's interface to CVODES to
  * integrate the equations.
  *
- * Keywords: combustion, reactor network, user-defined model, ignition delay
+ * .. tags:: C++, combustion, reactor network, user-defined model, ignition delay
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or
@@ -53,14 +52,21 @@ public:
         m_nEqs = m_nSpecies + 1;
     }
 
-    /**
-     * Evaluate the ODE right-hand-side function, ydot = f(t,y).
-     *   - overridden from FuncEval, called by the integrator during simulation.
-     * @param[in] t time.
-     * @param[in] y solution vector, length neq()
-     * @param[out] ydot rate of change of solution vector, length neq()
-     * @param[in] p sensitivity parameter vector, length nparams()
-     *   - note: sensitivity analysis isn't implemented in this example
+    /* %%
+     * Evaluate the ODE right-hand-side function, :math:`\dot{y} = f(t,y)`.
+     *
+     * Overridden from :ct:`FuncEval`, called by the integrator during simulation.
+     *
+     * :param t:
+     *     time
+     * :param y:
+     *     solution vector, length neq()
+     * :param ydot:
+     *     rate of change of solution vector, length neq()
+     * :param p:
+     *     sensitivity parameter vector, length nparams()
+     *
+     * note: sensitivity analysis isn't implemented in this example
      */
     void eval(double t, double* y, double* ydot, double* p) override {
         // the solution vector *y* is [T, Y_1, Y_2, ... Y_K], where T is the

samples/cxx/demo/demo.cpp

@@ -1,13 +1,12 @@
-/*!
- * @file demo.cpp
- *
- * Property Calculation Demo
+/*
+ * Property calculation demo
+ * =========================
  *
  * This demonstration program builds an object representing a reacting gas
  * mixture, and uses it to compute thermodynamic properties, chemical
  * equilibrium, and transport properties.
  *
- * Keywords: tutorial, thermodynamics, equilibrium, transport
+ * .. tags:: C++, tutorial, thermodynamics, equilibrium, transport
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/flamespeed/flamespeed.cpp

@@ -1,14 +1,16 @@
-/*!
- * @file flamespeed.cpp
- *
+/*
  * Freely-propagating flame
+ * ========================
  *
  * C++ demo program to compute flame speeds using GRI-Mech.
  *
- * Usage: flamespeed [equivalence_ratio] [refine_grid] [loglevel]
+ * Usage:
+ *
+ *     flamespeed [equivalence_ratio] [refine_grid] [loglevel]
  *
  * Requires: cantera >= 3.0
- * Keywords: combustion, 1D flow, premixed flame, flame speed, saving output
+ *
+ * .. tags:: C++, combustion, 1D flow, premixed flame, flame speed, saving output
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/gas_transport/gas_transport.cpp

@@ -1,13 +1,12 @@
-/*!
- * @file gas_transport.cpp
- *
+/*
  * Gas phase transport properties
+ * ==============================
  *
  * Construct a gas phase Solution object and use it to compute viscosity,
  * thermal conductivity, mixture-averaged diffusion coefficients, and thermal
  * diffusivities for a range of temperatures.
  *
- * Keywords: tutorial, transport, saving output
+ * .. tags:: C++, tutorial, transport, saving output
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/jacobian/derivative_speed.cpp

@@ -1,13 +1,12 @@
-/*!
- * @file derivative_speed.cpp
- *
+/*
  * Benchmark derivative evaluations
+ * ================================
  *
  * Calculate derivatives of reaction rates of progress and species production and
  * destruction rates with respect to temperature, pressure, molar concentration,
  * and mole fractions. Time evaluation for different chemical mechanisms.
  *
- * Keywords: kinetics, benchmarking
+ * .. tags:: C++, kinetics, benchmarking
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/kinetics1/example_utils.h

@@ -1,3 +1,8 @@
+// Example utilities
+// =================
+//
+// Defines some functions used by :doc:`kinetics1.cpp <kinetics1>`.
+
 // This file is part of Cantera. See License.txt in the top-level directory or
 // at https://cantera.org/license.txt for license and copyright information.
 

samples/cxx/kinetics1/kinetics1.cpp

@@ -1,12 +1,11 @@
-/*!
- * @file kinetics1.cpp
- *
- * Zero-dimensional kinetics
+/*
+ * Autoignition in a homogeneous reactor
+ * =====================================
  *
  * This example simulates autoignition of hydrogen in a constant pressure
  * reactor and saves the time history to files that can be used for plotting.
  *
- * Keywords: combustion, reactor network, ignition delay, saving output
+ * .. tags:: C++, combustion, reactor network, ignition delay, saving output
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/openmp_ignition/openmp_ignition.cpp

@@ -1,12 +1,11 @@
-/*!
- * @file openmp_ignition.cpp
- *
+/*
  * Ignition delay calculation with OpenMP
+ * ======================================
  *
  * This example shows how to use OpenMP to run multiple reactor network
  * calculations in parallel by using separate Cantera objects for each thread.
  *
- * Keywords: combustion, reactor network, ignition delay, parallel computing
+ * .. tags:: C++, combustion, reactor network, ignition delay, parallel computing
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or

samples/cxx/rankine/rankine.cpp

@@ -1,12 +1,11 @@
-/*!
- * @file rankine.cpp
- *
- * Open Rankine Cycle
+/*
+ * Open Rankine cycle
+ * ==================
  *
  * Calculate the thermodynamic states and efficiency of an open Rankine cycle
  * using a pure substance model for water.
  *
- * Keywords: thermodynamics, thermodynamic cycle, non-ideal fluid
+ * .. tags:: C++, thermodynamics, thermodynamic cycle, non-ideal fluid
  */
 
 // This file is part of Cantera. See License.txt in the top-level directory or