From f720a573db61b144fa27b35e2f950d1306418873 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Wed, 20 Sep 2023 11:54:39 -0400 Subject: [PATCH] [Doc] Add C++ examples to sphinx-gallery --- doc/SConscript | 14 ++++++- doc/sphinx/conf.py | 5 +++ doc/sphinx/index.rst | 1 + samples/cxx/LiC6_electrode/LiC6_electrode.cpp | 9 ++-- samples/cxx/README.rst | 2 + samples/cxx/bvp/BoundaryValueProblem.h | 12 ++++-- samples/cxx/bvp/blasius.cpp | 41 ++++++++++--------- samples/cxx/combustor/combustor.cpp | 11 +++-- samples/cxx/custom/custom.cpp | 32 +++++++++------ samples/cxx/demo/demo.cpp | 9 ++-- samples/cxx/flamespeed/flamespeed.cpp | 12 +++--- samples/cxx/gas_transport/gas_transport.cpp | 7 ++-- samples/cxx/jacobian/derivative_speed.cpp | 7 ++-- samples/cxx/kinetics1/example_utils.h | 5 +++ samples/cxx/kinetics1/kinetics1.cpp | 9 ++-- .../cxx/openmp_ignition/openmp_ignition.cpp | 7 ++-- samples/cxx/rankine/rankine.cpp | 9 ++-- 17 files changed, 111 insertions(+), 81 deletions(-) create mode 100644 samples/cxx/README.rst diff --git a/doc/SConscript b/doc/SConscript index 971fbc166..503be7349 100644 --- a/doc/SConscript +++ b/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 diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py index 804bb9e6d..31056ca7d 100644 --- a/doc/sphinx/conf.py +++ b/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 = { diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 53639ad1e..85708291c 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -16,5 +16,6 @@ format. matlab/index examples/python/index + examples/cxx/index _tags/tagsindex \ No newline at end of file diff --git a/samples/cxx/LiC6_electrode/LiC6_electrode.cpp b/samples/cxx/LiC6_electrode/LiC6_electrode.cpp index ec75b4bf3..be0633f40 100644 --- a/samples/cxx/LiC6_electrode/LiC6_electrode.cpp +++ b/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 diff --git a/samples/cxx/README.rst b/samples/cxx/README.rst new file mode 100644 index 000000000..3bf4d017c --- /dev/null +++ b/samples/cxx/README.rst @@ -0,0 +1,2 @@ +C++ Examples +============ diff --git a/samples/cxx/bvp/BoundaryValueProblem.h b/samples/cxx/bvp/BoundaryValueProblem.h index 9e347697e..2ae637e8f 100644 --- a/samples/cxx/bvp/BoundaryValueProblem.h +++ b/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 ` 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 diff --git a/samples/cxx/bvp/blasius.cpp b/samples/cxx/bvp/blasius.cpp index 5e699d1c7..dbd5efe99 100644 --- a/samples/cxx/bvp/blasius.cpp +++ b/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 `, 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 diff --git a/samples/cxx/combustor/combustor.cpp b/samples/cxx/combustor/combustor.cpp index d72a343d9..ca347658c 100644 --- a/samples/cxx/combustor/combustor.cpp +++ b/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 diff --git a/samples/cxx/custom/custom.cpp b/samples/cxx/custom/custom.cpp index e60c4e5fd..d50f66a68 100644 --- a/samples/cxx/custom/custom.cpp +++ b/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 diff --git a/samples/cxx/demo/demo.cpp b/samples/cxx/demo/demo.cpp index da6c0c80f..a72186472 100644 --- a/samples/cxx/demo/demo.cpp +++ b/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 diff --git a/samples/cxx/flamespeed/flamespeed.cpp b/samples/cxx/flamespeed/flamespeed.cpp index caf48db3c..09e7749ee 100644 --- a/samples/cxx/flamespeed/flamespeed.cpp +++ b/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 diff --git a/samples/cxx/gas_transport/gas_transport.cpp b/samples/cxx/gas_transport/gas_transport.cpp index fcd9b0975..bcbdfdf92 100644 --- a/samples/cxx/gas_transport/gas_transport.cpp +++ b/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 diff --git a/samples/cxx/jacobian/derivative_speed.cpp b/samples/cxx/jacobian/derivative_speed.cpp index ee63732e4..c44956275 100644 --- a/samples/cxx/jacobian/derivative_speed.cpp +++ b/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 diff --git a/samples/cxx/kinetics1/example_utils.h b/samples/cxx/kinetics1/example_utils.h index 23547ea30..d0a770001 100644 --- a/samples/cxx/kinetics1/example_utils.h +++ b/samples/cxx/kinetics1/example_utils.h @@ -1,3 +1,8 @@ +// Example utilities +// ================= +// +// Defines some functions used by :doc:`kinetics1.cpp `. + // 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. diff --git a/samples/cxx/kinetics1/kinetics1.cpp b/samples/cxx/kinetics1/kinetics1.cpp index 5cc2ca846..688abb672 100644 --- a/samples/cxx/kinetics1/kinetics1.cpp +++ b/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 diff --git a/samples/cxx/openmp_ignition/openmp_ignition.cpp b/samples/cxx/openmp_ignition/openmp_ignition.cpp index f4b44fe88..2d2a91f71 100644 --- a/samples/cxx/openmp_ignition/openmp_ignition.cpp +++ b/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 diff --git a/samples/cxx/rankine/rankine.cpp b/samples/cxx/rankine/rankine.cpp index 212687441..8b5bde5c0 100644 --- a/samples/cxx/rankine/rankine.cpp +++ b/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