[Doc] Add remaining Python examples to sphinx-gallery

Introduce a monkey patch to avoid executing specific examples that won't run under sphinx-gallery.
2026-08-08 20:18:24 -05:00 · 2023-10-03 11:23:39 -04:00
parent d005585e4d
commit c49c95d666
57 changed files with 402 additions and 157 deletions
@@ -61,6 +61,42 @@ sphinx_gallery_conf = {
    }
 }

+# Override sphinx-gallery's method for determining which examples should be executed.
+# There's really no way to achieve this with the `filename_pattern` option, and
+# `ignore_pattern` excludes the example entirely.
+skip_run = {
+    # multiprocessing can't see functions defined in __main__ when run by
+    # sphinx-gallery, at least on macOS.
+    "multiprocessing_viscosity.py",
+    # __file__ deliberately not available when run by sphinx-gallery
+    "flame_fixed_T.py",
+}
+
+def executable_script(src_file, gallery_conf):
+    """Validate if script has to be run according to gallery configuration.
+
+    Parameters
+    ----------
+    src_file : str
+        path to python script
+
+    gallery_conf : dict
+        Contains the configuration of Sphinx-Gallery
+
+    Returns
+    -------
+    bool
+        True if script has to be executed
+    """
+    filename = Path(src_file).name
+    if filename in skip_run:
+        return False
+    filename_pattern = gallery_conf["filename_pattern"]
+    execute = re.search(filename_pattern, src_file) and gallery_conf["plot_gallery"]
+    return execute
+
+import sphinx_gallery.gen_rst
+sphinx_gallery.gen_rst.executable_script = executable_script

 header_prefix = """
 :html_theme.sidebar_secondary.remove:
@@ -69,7 +105,6 @@ header_prefix = """

 """

-import sphinx_gallery.gen_rst
 sphinx_gallery.gen_rst.EXAMPLE_HEADER = header_prefix + sphinx_gallery.gen_rst.EXAMPLE_HEADER

 # Options for sphinx_tags extension
@@ -0,0 +1,2 @@
+Multiphase
+----------
@@ -1,9 +1,13 @@
 """
+Adiabatic flame temperature including solid carbon formation
+============================================================
+
 Adiabatic flame temperature and equilibrium composition for a fuel/air mixture
 as a function of equivalence ratio, including formation of solid carbon.

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: equilibrium, combustion, multiphase
+
+.. tags:: Python, equilibrium, combustion, multiphase
 """

 import cantera as ct
@@ -1,9 +1,13 @@
 """
+Equilibrium with charged species and multiple condensed phases
+==============================================================
+
 An equilibrium example with charged species in the gas phase
 and multiple condensed phases.

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: equilibrium, multiphase, plasma, saving output
+
+.. tags:: Python, equilibrium, multiphase, plasma, saving output
 """

 import cantera as ct
@@ -0,0 +1,2 @@
+1D reacting flows
+-----------------
@@ -1,9 +1,13 @@
 """
+Laminar flame speed calculation
+===============================
+
 A freely-propagating, premixed hydrogen flat flame with multicomponent
 transport properties.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, premixed flame, multicomponent transport,
+
+.. tags:: Python, combustion, 1D flow, premixed flame, multicomponent transport,
          saving output
 """

@@ -1,8 +1,12 @@
 """
+Burner-stabilized flame
+=======================
+
 A burner-stabilized lean premixed hydrogen-oxygen flame at low pressure.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, premixed flame, saving output,
+
+.. tags:: Python, combustion, 1D flow, premixed flame, saving output,
          multicomponent transport
 """

@@ -1,8 +1,12 @@
 """
+Counterflow diffusion flame
+===========================
+
 An opposed-flow ethane/air diffusion flame

 Requires: cantera >= 3.0, matplotlib >= 2.0
-Keywords: combustion, 1D flow, diffusion flame, strained flame, plotting,
+
+.. tags:: Python, combustion, 1D flow, diffusion flame, strained flame, plotting,
          saving output
 """

@@ -2,6 +2,9 @@
 # at https://cantera.org/license.txt for license and copyright information.

 """
+Scaling of diffusion flames with pressure and strain rate
+=========================================================
+
 This example creates two batches of counterflow diffusion flame simulations.
 The first batch computes counterflow flames at increasing pressure, the second
 at increasing strain rates.
@@ -14,7 +17,8 @@ This example can, for example, be used to iterate to a counterflow diffusion fla
 awkward pressure and strain rate, or to create the basis for a flamelet table.

 Requires: cantera >= 3.0, matplotlib >= 2.0
-Keywords: combustion, 1D flow, extinction, diffusion flame, strained flame,
+
+.. tags:: Python, combustion, 1D flow, extinction, diffusion flame, strained flame,
          saving output, plotting
 """

@@ -2,6 +2,9 @@
 # at https://cantera.org/license.txt for license and copyright information.

 """
+Diffusion flame extinction strain rate
+======================================
+
 This example computes the extinction point of a counterflow diffusion flame.
 A hydrogen-oxygen diffusion flame at 1 bar is studied.

@@ -10,7 +13,8 @@ The tutorial makes use of the scaling rules derived by Fiala and Sattelmayer
 explanation. Also, please don't forget to cite it if you make use of it.

 Requires: cantera >= 3.0, matplotlib >= 2.0
-Keywords: combustion, 1D flow, diffusion flame, strained flame, extinction,
+
+.. tags:: Python, combustion, 1D flow, diffusion flame, strained flame, extinction,
          saving output, plotting
 """

@@ -1,9 +1,13 @@
 """
+Burner-stabilized flame with imposed temperature profile
+========================================================
+
 A burner-stabilized, premixed methane/air flat flame with multicomponent
 transport properties and a specified temperature profile.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, burner-stabilized flame, premixed flame, plotting,
+
+.. tags:: Python, combustion, 1D flow, burner-stabilized flame, premixed flame, plotting,
          saving output
 """

@@ -12,7 +16,7 @@ import numpy as np
 import cantera as ct


-################################################################
+# %%
 # parameter values
 p = ct.one_atm  # pressure
 tburner = 373.7  # burner temperature
@@ -25,10 +29,9 @@ width = 0.01  # m
 loglevel = 1  # amount of diagnostic output (0 to 5)
 refine_grid = True  # 'True' to enable refinement

-################ create the gas object ########################
-#
-# This object will be used to evaluate all thermodynamic, kinetic, and
-# transport properties
+# %%
+# Create the gas object. This object will be used to evaluate all thermodynamic,
+# kinetic, and transport properties
 gas = ct.Solution('gri30.yaml')

 # set its state to that of the unburned gas at the burner
@@ -40,7 +43,8 @@ f = ct.BurnerFlame(gas=gas, width=width)
 # set the mass flow rate at the burner
 f.burner.mdot = mdot

-# read temperature vs. position data from a file.
+# %%
+# Read temperature vs. position data from a file.
 # The file is assumed to have one z, T pair per line, separated by a comma.
 # The data file must be stored in the same folder as this script.
 data_file = Path(__file__).parent.joinpath('tdata.dat')
@@ -50,6 +54,7 @@ zloc /= max(zloc)
 # set the temperature profile to the values read in
 f.flame.set_fixed_temp_profile(zloc, tvalues)

+# %%
 # show the initial estimate for the solution
 f.show()

@@ -1,10 +1,14 @@
 """
+Saving, loading, and restarting 1D calculations
+===============================================
+
 A freely-propagating, premixed methane-air flame.
 Examples of saving and loading a flame and restarting
 with different initial guesses.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, flame speed, premixed flame, saving output
+
+.. tags:: Python, combustion, 1D flow, flame speed, premixed flame, saving output
 """
 import sys
 from pathlib import Path
@@ -1,10 +1,14 @@
 """
+Laminar flame speed sensitivity analysis
+========================================
+
 Sensitivity analysis for a freely-propagating, premixed methane-air
 flame. Computes the sensitivity of the laminar flame speed with respect
 to each reaction rate constant.

 Requires: cantera >= 2.5.0
-Keywords: combustion, 1D flow, flame speed, premixed flame, sensitivity analysis
+
+.. tags:: Python, combustion, 1D flow, flame speed, premixed flame, sensitivity analysis
 """

 import cantera as ct
@@ -1,8 +1,12 @@
 """
+Burner-stabilized flame including ionized species
+=================================================
+
 A burner-stabilized premixed methane-air flame with charged species.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, burner-stabilized flame, plasma, premixed flame
+
+.. tags:: Python, combustion, 1D flow, burner-stabilized flame, plasma, premixed flame
 """

 from pathlib import Path
@@ -1,8 +1,12 @@
 """
+Freely-propagating flame with charged species
+=============================================
+
 A freely-propagating, premixed methane-air flat flame with charged species.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, burner-stabilized flame, plasma, premixed flame
+
+.. tags:: Python, combustion, 1D flow, burner-stabilized flame, plasma, premixed flame
 """

 from pathlib import Path
@@ -1,11 +1,13 @@
 """
-An opposed-flow premixed strained flame
+Opposed-flow premixed strained flame
+====================================

 This script simulates a lean hydrogen-oxygen flame stabilized in a strained
 flowfield, with an opposed flow consisting of equilibrium products.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, premixed flame, strained flame
+
+.. tags:: Python, combustion, 1D flow, premixed flame, strained flame
 """

 from pathlib import Path
@@ -1,10 +1,15 @@
 """
-Simulate two counter-flow jets of reactants shooting into each other. This
-simulation differs from the similar premixed_counterflow_flame.py example as the
-latter simulates a jet of reactants shooting into products.
+Symmetric premixed twin flame
+=============================
+
+Simulate two counter-flow jets of reactants shooting into each other. This simulation
+differs from the similar :doc:`premixed_counterflow_flame.py
+<premixed_counterflow_flame>` example as the latter simulates a jet of reactants
+shooting into products.

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, premixed flame, strained flame, plotting
+
+.. tags:: Python, combustion, 1D flow, premixed flame, strained flame, plotting
 """

 import sys
@@ -1,5 +1,6 @@
 """
-A detached flat flame stabilized at a stagnation point
+Detached flat flame stabilized at a stagnation point
+====================================================

 This script simulates a lean hydrogen-oxygen flame stabilized in a strained
 flowfield at an axisymmetric stagnation point on a non-reacting surface. The
@@ -15,7 +16,8 @@ points would be concentrated upstream of the flame, where the flamefront had
 been previously. (To see this, try setting prune to zero.)

 Requires: cantera >= 3.0
-Keywords: combustion, 1D flow, premixed flame, strained flame
+
+.. tags:: Python, combustion, 1D flow, premixed flame, strained flame
 """

 from pathlib import Path
@@ -1,5 +1,7 @@
-# coding: utf-8
 """
+Ignition delay time using the Redlich-Kwong real gas model
+==========================================================
+
 Ignition delay time computations in a high-pressure reflected shock tube
 reactor, comparing ideal gas and Redlich-Kwong real gas models.

@@ -17,7 +19,8 @@ Other than the typical Cantera dependencies, plotting functions require that
 you have matplotlib (https://matplotlib.org/) installed.

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, non-ideal fluid, ignition delay, plotting
+
+.. tags:: Python, combustion, reactor network, non-ideal fluid, ignition delay, plotting
 """

 # Dependencies: numpy, and matplotlib
@@ -1,11 +1,9 @@
 """
-Short description: reactor cascade model for reactive flows in inert porous media
-based on extensible reactors. Showcases adding a temperature equation for a
-solid-phase and custom heat transfer/radiation models.
+Reactor cascade model for reactive flows in inert porous media
+==============================================================

-Code by Thorsten Zirwes and Guillaume Vignat
-Stanford University & Karlsruhe Institute of Technology (KIT)
-2023
+Showcases the use of `ExtensibleReactor` to add a temperature equation for a solid-phase
+and custom heat transfer/radiation models.

 This code implements a reactor cascade model for the simulation of reactive
 flows in porous media. The gas mixture with fuel and oxidizer flows through
@@ -23,9 +21,6 @@ so that mass controllers and pressure valves are not required. The code is writt
 a general way to support an arbitrary number of reactors and an arbitrary number of
 burner sections with different physical properties.

-The implemented equations make use of Cantera's extensible reactor models.
-Therefore, Cantera version 2.6.0 or higher is required.
-
 The porous media burner considered in this example is a cylindrical tube filled
 three different porous materials: a porous ceramic made from a Yttria-stabilized
 Zirconia Alumina (YZA) section with length of 2 inches and pore density of 40 pores per
@@ -35,14 +30,15 @@ hydrogen dilution in the measurements. Next, a one inch section with a porous ce
 made from silicon carbide (SiC) with 3 PPI is used and finally a 1 inch section of SiC
 with 10 PPI. A flame stabilizes at the interface between the YZA and 3 PPI SiC.

+.. code:: none

-          |--- two inches --- | --- one inch ---| --- one inch --- |
-          __________________________________________________________
-fuel
- +   =>      YZA 40 PPI       |     SiC 3 PPI   |   SiC 10 PPI       => burnt
-air       __________________________________________________________    gas
+             |--- two inches --- | --- one inch ---| --- one inch --- |
+             __________________________________________________________
+   fuel
+    +   =>      YZA 40 PPI       |     SiC 3 PPI   |   SiC 10 PPI       => burnt
+   air       __________________________________________________________    gas

-                inert            flame location   heat recirculation
+                   inert            flame location   heat recirculation

 This example simplifies the complex interaction between heat transport in the gas-phase
 and solid-phase by using a reactor cascade. While key trends from the measurements can
@@ -52,8 +48,9 @@ modeling of internal heat recirculation through heat transfer, conduction and
 radiation. For more realistic and quantitative predictions, running 1D simulations with
 full radiation transport is required.

-More details about the governing equations, submodels and physical setup and
-corresponding experiments can be found in
+Initial code by Thorsten Zirwes and Guillaume Vignat, Stanford University & Karlsruhe
+Institute of Technology (KIT). More details about the governing equations, submodels and
+physical setup and corresponding experiments can be found in

    Experimental and numerical investigation of flame stabilization and
    pollutant formation in matrix stabilized ammonia-hydrogen combustion,
@@ -62,8 +59,9 @@ corresponding experiments can be found in
    Combustion and Flame, 250 (https://doi.org/10.1016/j.combustflame.2023.112642)

 Requires: cantera >= 2.6.0, matplotlib >= 2.0
-Keywords: user-defined model, reactor network, combustion, porous media, heat transfer,
-          radiative heat transfer
+
+.. tags:: Python, user-defined model, reactor network, combustion, porous media,
+          heat transfer, radiative heat transfer
 """

 import matplotlib.pyplot as plt
@@ -0,0 +1,2 @@
+Reactor networks
+----------------
@@ -1,4 +1,7 @@
 """
+Combustor residence time
+========================
+
 Calculate steady-state solutions for a combustor, modeled as a single well-stirred
 reactor, for different residence times.

@@ -6,13 +9,14 @@ We are interested in the steady-state burning solution. This example explores
 the effect of changing the residence time on completeness of reaction (through
 the burned gas temperature) and on the total heat release rate.

-Demonstrates the use of a MassFlowController where the mass flow rate function
+Demonstrates the use of a `MassFlowController` where the mass flow rate function
 depends on variables other than time by capturing these variables from the
-enclosing scope. Also shows the use of a PressureController to create a constant
+enclosing scope. Also shows the use of a `PressureController` to create a constant
 pressure reactor with a fixed volume.

 Requires: cantera >= 3.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, well-stirred reactor, plotting
+
+.. tags:: Python, combustion, reactor network, well-stirred reactor, plotting
 """

 import numpy as np
@@ -1,4 +1,7 @@
 """
+Integrating constant pressure ignition using SciPy
+==================================================
+
 Solve a constant pressure ignition problem where the governing equations are
 implemented in Python.

@@ -10,7 +13,8 @@ case, the SciPy wrapper for VODE is used, which uses the same variable-order BDF
 methods as the Sundials CVODES solver used by Cantera.

 Requires: cantera >= 2.5.0, scipy >= 0.19, matplotlib >= 2.0
-Keywords: combustion, reactor network, ignition delay, user-defined model, plotting
+
+.. tags:: Python, combustion, reactor network, ignition delay, user-defined model, plotting
 """

 import cantera as ct
@@ -1,12 +1,15 @@
 """
+Using `ExtensibleReactor` to implement wall inertia
+===================================================
+
 Solve an ignition problem where the normal reactor governing equations are
 extended with additional equations implemented in Python.

-This demonstrates an approach for solving problems where Cantera's built-in
-reactor models are not sufficient for describing the system in question. Unlike
-the 'custom.py' example, in this example Cantera's existing Reactor and
-ReactorNet code is still used, with only the modifications to the standard
-equations implemented in Python by extending the ExtensibleReactor class.
+This demonstrates an approach for solving problems where Cantera's built-in reactor
+models are not sufficient for describing the system in question. Unlike the
+:doc:`custom.py <custom>` example, in this example Cantera's existing `Reactor` and
+`ReactorNet` code is still used, with only the modifications to the standard equations
+implemented in Python by extending the `ExtensibleReactor` class.

 Wall objects in Cantera are normally massless, with the velocity either imposed
 or proportional to the pressure difference. Here, we simulate a wall where the
@@ -15,7 +18,8 @@ determined by integrating the equation of motion. This requires adding a new
 variable to the reactor's state vector which represents the wall velocity.

 Requires: cantera >= 3.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, user-defined model, plotting
+
+.. tags:: Python, combustion, reactor network, user-defined model, plotting
 """

 import cantera as ct
@@ -1,13 +1,17 @@
 """
+Soot precursor formation with time-varying mass flow rate
+=========================================================
+
 Simulation of fuel injection into a vitiated air mixture to show formation of
 soot precursors.

 Demonstrates the use of a user-supplied function for the mass flow rate through
-a MassFlowController, and the use of the SolutionArray class to store results
+a `MassFlowController`, and the use of the `SolutionArray` class to store results
 during reactor network integration and use these results to generate plots.

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, kinetics, pollutant formation, plotting
+
+.. tags:: Python, combustion, reactor network, kinetics, pollutant formation, plotting
 """

 import numpy as np
@@ -1,12 +1,14 @@
 """
-Simulation of a (gaseous) Diesel-type internal combustion engine.
+Diesel-type internal combustion engine simulation with gaseous fuel
+===================================================================

 The simulation uses n-Dodecane as fuel, which is injected close to top dead
 center. Note that this example uses numerous simplifying assumptions and
 thus serves for illustration purposes only.

 Requires: cantera >= 3.0, scipy >= 0.19, matplotlib >= 2.0
-Keywords: combustion, thermodynamics, internal combustion engine,
+
+.. tags:: Python, combustion, thermodynamics, internal combustion engine,
          thermodynamic cycle, reactor network, plotting, pollutant formation
 """

@@ -1,5 +1,6 @@
 """
-Mixing two streams.
+Mixing two streams
+==================

 Since reactors can have multiple inlets and outlets, they can be used to
 implement mixers, splitters, etc. In this example, air and methane are mixed
@@ -13,10 +14,11 @@ ignored. In general, reaction mechanisms for downstream reactors should
 contain all species that might be present in any upstream reactor.

 Compare this approach for the transient problem to the method used for the
-steady-state problem in thermo/mixing.py.
+steady-state problem in :doc:`mixing.py <../thermo/mixing>`.

 Requires: cantera >= 2.5.0
-Keywords: thermodynamics, reactor network, mixture
+
+.. tags:: Python, thermodynamics, reactor network, mixture
 """

 import cantera as ct
@@ -1,4 +1,7 @@
-"""
+r"""
+Continuously stirred tank reactor with periodic behavior
+========================================================
+
 This example illustrates a continuously stirred tank reactor (CSTR) with steady
 inputs but periodic interior state.

@@ -6,19 +9,22 @@ A stoichiometric hydrogen/oxygen mixture is introduced and reacts to produce
 water.  But since water has a large efficiency as a third body in the chain
 termination reaction

-       H + O2 + M = HO2 + M
+.. math::
+
+       \mathrm{ H + O_2 + M \rightleftharpoons HO_2 + M }

 as soon as a significant amount of water is produced the reaction stops. After
 enough time has passed that the water is exhausted from the reactor, the mixture
 explodes again and the process repeats. This explanation can be verified by
-decreasing the rate for reaction 7 in file h2o2.yaml and re-running the
+decreasing the rate for reaction 7 in file ``h2o2.yaml`` and re-running the
 example.

-Acknowledgments: The idea for this example and an estimate of the conditions
+*Acknowledgments*: The idea for this example and an estimate of the conditions
 needed to see the oscillations came from Bob Kee, Colorado School of Mines

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, well-stirred reactor, plotting
+
+.. tags:: Python, combustion, reactor network, well-stirred reactor, plotting
 """

 import cantera as ct
@@ -1,10 +1,14 @@
 """
+Plug flow reactor modeling approaches
+=====================================
+
 This example solves a plug-flow reactor problem of hydrogen-oxygen combustion.
 The PFR is computed by two approaches: The simulation of a Lagrangian fluid
 particle, and the simulation of a chain of reactors.

 Requires: cantera >= 3.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, plug flow reactor
+
+.. tags:: Python, combustion, reactor network, plug flow reactor
 """

 import cantera as ct
@@ -1,9 +1,14 @@
 """
+Reactors separated by a moving piston
+=====================================
+
 Two reactors separated by a piston that moves with a speed proportional to the pressure
 difference between the reactors.

-Gas 1: a stoichiometric H2/O2/Ar mixture
-Gas 2: a wet CO/O2 mixture
+- Gas 1: a stoichiometric H2/O2/Ar mixture
+- Gas 2: a wet CO/O2 mixture
+
+.. code:: none

    -------------------------------------
    |          ||                       |
@@ -13,13 +18,15 @@ Gas 2: a wet CO/O2 mixture
    |          ||                       |
    -------------------------------------

+
 The two volumes are connected by an adiabatic free piston. The piston speed is
 proportional to the pressure difference between the two chambers.

 Note that each side uses a *different* reaction mechanism

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, plotting
+
+.. tags:: Python, combustion, reactor network, plotting
 """

 import sys
@@ -1,10 +1,13 @@
-# -*- coding: utf-8 -*-
 """
+Acceleration of reactor integration using a sparse preconditioned solver
+========================================================================
+
 Ideal gas, constant-pressure, adiabatic kinetics simulation that compares preconditioned
 and non-preconditioned integration of nDodecane.

 Requires: cantera >= 3.0.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, preconditioner
+
+.. tags:: Python, combustion, reactor network, preconditioner
 """
 import cantera as ct
 import numpy as np
@@ -1,8 +1,10 @@
 """
-Constant-pressure, adiabatic kinetics simulation.
+Constant-pressure, adiabatic kinetics simulation
+================================================

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, plotting
+
+.. tags:: Python, combustion, reactor network, plotting
 """

 import sys
@@ -1,4 +1,7 @@
-"""
+r"""
+Reactors with walls and heat transfer
+=====================================
+
 Two reactors connected with a piston, with heat loss to the environment

 This script simulates the following situation. A closed cylinder with volume 2
@@ -6,8 +9,8 @@ m^3 is divided into two equal parts by a massless piston that moves with speed
 proportional to the pressure difference between the two sides. It is
 initially held in place in the middle. One side is filled with 1000 K argon at
 20 atm, and the other with a combustible 500 K methane/air mixture at 0.1 atm
-(phi = 1.1). At t = 0 the piston is released and begins to move due to the
-large pressure difference, compressing and heating the methane/air mixture,
+(:math:`\phi = 1.1`). At :math:`t = 0`, the piston is released and begins to move due
+to the large pressure difference, compressing and heating the methane/air mixture,
 which eventually explodes. At the same time, the argon cools as it expands.
 The piston allows heat transfer between the reactors and some heat is lost
 through the outer cylinder walls to the environment.
@@ -16,7 +19,8 @@ Note that this simulation, being zero-dimensional, takes no account of shock
 wave propagation. It is somewhat artificial, but nevertheless instructive.

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, plotting
+
+.. tags:: combustion, reactor network, plotting
 """

 import sys
@@ -1,8 +1,10 @@
 """
 Constant-pressure, adiabatic kinetics simulation with sensitivity analysis
+==========================================================================

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: combustion, reactor network, sensitivity analysis, plotting
+
+.. tags:: Python, combustion, reactor network, sensitivity analysis, plotting
 """

 import sys
@@ -1,12 +1,15 @@
 """
-This example solves a plug flow reactor problem with surface chemistry. The specific
-problem simulated is the partial oxidation of methane over a platinum catalyst in a
-packed bed reactor. This example solves the DAE system directly, using the FlowReactor
+Plug flow reactor with surface chemistry
+========================================
+
+This example simulates the partial oxidation of methane over a platinum catalyst in a
+packed bed reactor. This example solves the DAE system directly, using the `FlowReactor`
 class and the SUNDIALS IDA solver, in contrast to the approximation as a chain of
-steady-state WSRs used in surf_pfr_chain.py.
+steady-state WSRs used in :doc:`surf_pfr_chain.py <surf_pfr_chain>`.

 Requires: cantera >= 3.0.0
-Keywords: catalysis, reactor network, surface chemistry, plug flow reactor,
+
+.. tags:: Python, catalysis, reactor network, surface chemistry, plug flow reactor,
          packed bed reactor
 """

@@ -1,12 +1,16 @@
 """
-This example solves a plug flow reactor problem, where the chemistry is
-surface chemistry. The specific problem simulated is the partial oxidation of
-methane over a platinum catalyst in a packed bed reactor. To avoid needing to solve a
-DAE system, the PFR is approximated as a chain of successive WSRs. See surf_pfr.py
-for a more advanced implementation that solves the DAE system directly.
+Plug flow reactor modeled as a chain of well stirred reactors
+=============================================================
+
+This example solves a plug flow reactor problem, where the chemistry is surface
+chemistry. The specific problem simulated is the partial oxidation of methane over a
+platinum catalyst in a packed bed reactor. To avoid needing to solve a DAE system, the
+PFR is approximated as a chain of successive WSRs. See :doc:`surf_pfr.py <surf_pfr>` for
+a more advanced implementation that solves the DAE system directly.

 Requires: cantera >= 3.0
-Keywords: catalysis, reactor network, surface chemistry, plug flow reactor,
+
+.. tags:: Python, catalysis, reactor network, surface chemistry, plug flow reactor,
          packed bed reactor
 """

@@ -1,4 +1,7 @@
 """
+Plug flow reactor: silicon nitride deposition
+=============================================
+
 A 1-D steady state plug-flow reactor demonstrating silicon nitride (Si3N4) deposition
 from ammonia (NH3) and silicon tetrafluoride (SiF4).

@@ -7,15 +10,16 @@ Assumes a constant temperature, frictionless, cylindrical reactor.
 Based off the Jupyter notebook created by Yuanjie Jiang, which corresponds to the
 original example from:

-R.S. Larson. "PLUG: A FORTRAN program for the analysis of PLUG flow reactors with
-gas-phase and surface chemistry", Sandia Report SAND-96-8211, 1996.
-https://doi.org/10.2172/204257
+    R.S. Larson. "PLUG: A FORTRAN program for the analysis of PLUG flow reactors with
+    gas-phase and surface chemistry", Sandia Report SAND-96-8211, 1996.
+    https://doi.org/10.2172/204257

 The results are somewhat different from those in the Larson report in part due to the
 fact that this example does not include the frictional pressure drop.

 Requires: cantera >= 3.0, matplotlib >= 2.0
-Keywords: catalysis, plug flow reactor, reactor network, surface chemistry
+
+.. tags:: Python, catalysis, plug flow reactor, reactor network, surface chemistry
 """

 import numpy as np
@@ -0,0 +1,2 @@
+Surface chemistry
+-----------------
@@ -1,5 +1,6 @@
 """
 Catalytic combustion of methane on platinum
+===========================================

 This script solves a catalytic combustion problem. A stagnation flow is set
 up, with a gas inlet 10 cm from a platinum surface at 900 K. The lean,
@@ -11,7 +12,8 @@ The catalytic combustion mechanism is from Deutschmann et al., 26th
 Symp. (Intl.) on Combustion,1996 pp. 1747-1754

 Requires: cantera >= 3.0
-Keywords: catalysis, combustion, 1D flow, surface chemistry
+
+.. tags:: Python, catalysis, combustion, 1D flow, surface chemistry
 """

 import numpy as np
@@ -1,16 +1,18 @@
 """
-A CVD example simulating growth of a diamond film
+Growth of diamond film using CVD
+================================

-This example computes the growth rate of a diamond film according to a
-simplified version of a particular published growth mechanism (see file
-diamond.yaml for details). Only the surface coverage equations are solved here;
-the gas composition is fixed. (For an example of coupled gas-phase and
-surface, see catalytic_combustion.py.) Atomic hydrogen plays an important
-role in diamond CVD, and this example computes the growth rate and surface
+This example computes the growth rate of a diamond film according to a simplified
+version of a particular published growth mechanism (see file ``diamond.yaml`` for
+details). Only the surface coverage equations are solved here; the gas composition is
+fixed. (For an example of coupled gas-phase and surface, see
+:doc:`catalytic_combustion.py <catalytic_combustion>`.) Atomic hydrogen plays an
+important role in diamond CVD, and this example computes the growth rate and surface
 coverages as a function of [H] at the surface for fixed temperature and [CH3].

 Requires: cantera >= 2.6.0, pandas >= 0.25.0, matplotlib >= 2.0
-Keywords: surface chemistry, kinetics
+
+.. tags:: Python, surface chemistry, kinetics
 """

 import csv
@@ -1,25 +1,30 @@
 """
+Lithium-ion battery
+===================
+
 This example calculates the cell voltage of a lithium-ion battery at
 given temperature, pressure, current, and range of state of charge (SOC).

 The thermodynamics are based on a graphite anode and a LiCoO2 cathode,
-modeled using the 'BinarySolutionTabulatedThermo' class.
+modeled using the :ct:`BinarySolutionTabulatedThermo` class.
 Further required cell parameters are the electrolyte ionic resistance, the
 stoichiometry ranges of the active materials (electrode balancing), and the
 surface area of the active materials.

 The functionality of this example is presented in greater detail in a jupyter
 notebook as well as the reference (which also describes the derivation of the
-'BinarySolutionTabulatedThermo' class):
+:ct:`BinarySolutionTabulatedThermo` class):

 Reference:
-M. Mayur, S. C. DeCaluwe, B. L. Kee, W. G. Bessler, “Modeling and simulation
-of the thermodynamics of lithium-ion battery intercalation materials in the
-open-source software Cantera,” Electrochim. Acta 323, 134797 (2019),
-https://doi.org/10.1016/j.electacta.2019.134797
+
+    M. Mayur, S. C. DeCaluwe, B. L. Kee, W. G. Bessler, “Modeling and simulation
+    of the thermodynamics of lithium-ion battery intercalation materials in the
+    open-source software Cantera,” Electrochim. Acta 323, 134797 (2019),
+    https://doi.org/10.1016/j.electacta.2019.134797

 Requires: cantera >= 2.6.0, matplotlib >= 2.0
-Keywords: surface chemistry, kinetics, electrochemistry, battery, plotting
+
+.. tags:: Python, surface chemistry, kinetics, electrochemistry, battery, plotting
 """

 import cantera as ct
@@ -1,4 +1,7 @@
 """
+Solid oxide fuel cell using elementary kinetics
+===============================================
+
 A simple model of a solid oxide fuel cell.

 Unlike most SOFC models, this model does not use semi-empirical Butler-Volmer
@@ -8,17 +11,19 @@ transfer. As this script will demonstrate, this approach allows computing the
 OCV (it does not need to be separately specified), as well as polarization
 curves.

-NOTE: The parameters here, and in the input file sofc.yaml, are not to be
-relied upon for a real SOFC simulation! They are meant to illustrate only how
-to do such a calculation in Cantera. While some of the parameters may be close
-to real values, others are simply set arbitrarily to give reasonable-looking
-results.
+.. caution::

-It is recommended that you read input file sofc.yaml before reading or running
-this script!
+    The parameters here, and in the input file ``sofc.yaml``, are not to be relied upon
+    for a real SOFC simulation! They are meant to illustrate only how to do such a
+    calculation in Cantera. While some of the parameters may be close to real values,
+    others are simply set arbitrarily to give reasonable-looking results.
+
+    It is recommended that you read input file ``sofc.yaml`` before reading or running
+    this script.

 Requires: cantera >= 2.6.0
-Keywords: kinetics, electrochemistry, surface chemistry, fuel cell
+
+.. tags:: Python, kinetics, electrochemistry, surface chemistry, fuel cell
 """

 import cantera as ct
@@ -0,0 +1,2 @@
+Thermodynamics
+--------------
@@ -1,6 +1,9 @@
 """
-This example demonstrates (1). the four different dependency models available
-for coverage-dependent enthalpy and entropy calculations and (2). capability
+Surface with coverage-dependent thermo
+======================================
+
+This example demonstrates (1) the four different dependency models available
+for coverage-dependent enthalpy and entropy calculations and (2) capability
 of including self-interaction but also cross-interaction among different
 surface species.

@@ -17,7 +20,8 @@ interaction. The CO* enthalpy is plotted as a function of CO* and O*
 coverages.

 Requires: cantera >= 3.0.0, matplotlib >= 2.0
-Keywords: thermodynamics, surface chemistry, catalysis
+
+.. tags:: Python, thermodynamics, surface chemistry, catalysis
 """

 import cantera as ct
@@ -1,8 +1,11 @@
 """
+Critical state properties
+=========================
+
 Print the critical state properties for the fluids for which Cantera has
 built-in liquid/vapor equations of state.

-Keywords: thermodynamics, multiphase, non-ideal fluid
+.. tags:: Python, thermodynamics, multiphase, non-ideal fluid
 """

 import cantera as ct
@@ -1,18 +1,24 @@
 """
+Equivalence ratio
+=================
+
 This example demonstrates how to set a mixture according to equivalence ratio
 and mixture fraction.

 Requires: cantera >= 2.6.0
-Keywords: combustion, thermodynamics, mixture
+
+.. tags:: Python, combustion, thermodynamics, mixture
 """

 import cantera as ct

 gas = ct.Solution('gri30.yaml')

+# %%
 # Define the oxidizer composition, here air with 21 mol-% O2 and 79 mol-% N2
 air = "O2:0.21,N2:0.79"

+# %%
 # Set the mixture composition according to the stoichiometric mixture
 # (equivalence ratio phi = 1). The fuel composition in this example
 # is set to 100 mol-% CH4 and the oxidizer to 21 mol-% O2 and 79 mol-% N2.
@@ -20,31 +26,35 @@ air = "O2:0.21,N2:0.79"
 # and pressure constant
 gas.set_equivalence_ratio(phi=1.0, fuel="CH4:1", oxidizer=air)

+# %%
 # If fuel or oxidizer consist of a single species, a short hand notation can be
-# used, for example fuel="CH4" is equivalent to fuel="CH4:1".
+# used, for example ``fuel="CH4"`` is equivalent to ``fuel="CH4:1"``.
 # By default, the compositions of fuel and oxidizer are interpreted as mole
 # fractions. If the compositions are given in mass fractions, an
 # additional argument can be provided. Here, the fuel is 100 mass-% CH4
 # and the oxidizer is 23.3 mass-% O2 and 76.7 mass-% N2
 gas.set_equivalence_ratio(1.0, fuel="CH4:1", oxidizer="O2:0.233,N2:0.767", basis='mass')

+# %%
 # This function can be used to compute the equivalence ratio for any mixture.
 # The first two arguments specify the compositions of the fuel and oxidizer.
-# An optional third argument "basis" indicates if fuel and oxidizer compositions
+# An optional third argument ``basis``` indicates if fuel and oxidizer compositions
 # are provided in terms of mass or mole fractions. Default is mole fractions.
 # Note that for all functions shown here, the compositions are normalized
 # internally so the species fractions do not have to sum to unity
 phi = gas.equivalence_ratio(fuel="CH4:1", oxidizer="O2:233,N2:767", basis='mass')
 print(f"phi = {phi:1.3f}")

+# %%
 # If the compositions of fuel and oxidizer are unknown, the function can
 # be called without arguments. This assumes that all C, H and S atoms come from
 # the fuel and all O atoms from the oxidizer. In this example, the fuel was set
-# to be pure CH4 and the oxidizer O2:0.233,N2:0.767 so that the assumption is true
+# to be pure CH4 and the oxidizer ``O2:0.233, N2:0.767`` so that the assumption is true
 # and the same equivalence ratio as above is computed
 phi = gas.equivalence_ratio()
 print(f"phi = {phi:1.3f}")

+# %%
 # Instead of working with equivalence ratio, mixture fraction can be used.
 # The mixture fraction is always kg fuel / (kg fuel + kg oxidizer), independent
 # of the basis argument. For example, the mixture fraction Z can be computed as
@@ -52,6 +62,7 @@ print(f"phi = {phi:1.3f}")
 Z = gas.mixture_fraction(fuel="CH4:1", oxidizer=air)
 print(f"Z = {Z:1.3f}")

+# %%
 # By default, the mixture fraction is the Bilger mixture fraction. Instead,
 # a mixture fraction based on a single element can be used. In this example,
 # the following two ways of computing Z are the same:
@@ -60,16 +71,19 @@ print(f"Z(Bilger mixture fraction) = {Z:1.3f}")
 Z = gas.mixture_fraction(fuel="CH4:1", oxidizer=air, element="C")
 print(f"Z(mixture fraction based on C) = {Z:1.3f}")

+# %%
 # Since the fuel in this example is pure methane and the oxidizer is air,
 # the mixture fraction is the same as the mass fraction of methane in the mixture
 print(f"mass fraction of CH4 = {gas['CH4'].Y[0]:1.3f}")

+# %%
 # To set a mixture according to the mixture fraction, the following function
 # can be used. In this example, the final fuel/oxidizer mixture
 # contains 5.5 mass-% CH4:
 gas.set_mixture_fraction(0.055, fuel="CH4:1", oxidizer=air)
 print(f"mass fraction of CH4 = {gas['CH4'].Y[0]:1.3f}")

+# %%
 # Mixture fraction and equivalence ratio are invariant to the reaction progress.
 # For example, they stay constant if the mixture composition changes to the burnt
 # state or for any intermediate state. Fuel and oxidizer compositions for all functions
@@ -82,8 +96,9 @@ Z_burnt = gas.mixture_fraction(fuel, air)
 print(f"phi(burnt) = {phi_burnt:1.3f}")
 print(f"Z(burnt) = {Z_burnt:1.3f}")

+# %%
 # If fuel and oxidizer compositions are specified consistently, then
-# equivalence_ratio and set_equivalence_ratio are consistent as well, as
+# ``equivalence_ratio`` and ``set_equivalence_ratio`` are consistent as well, as
 # shown in the following example with arbitrary fuel and oxidizer compositions:
 gas.set_equivalence_ratio(2.5, fuel="CH4:1,O2:0.01,CO:0.05,N2:0.1",
                          oxidizer="O2:0.2,N2:0.8,CO2:0.05,CH4:0.01")
@@ -92,6 +107,7 @@ phi = gas.equivalence_ratio(fuel="CH4:1,O2:0.01,CO:0.05,N2:0.1",
                            oxidizer="O2:0.2,N2:0.8,CO2:0.05,CH4:0.01")
 print(f"phi = {phi:1.3f}") # prints 2.5

+# %%
 # Without specifying the fuel and oxidizer compositions, it is assumed that
 # all C, H and S atoms come from the fuel and all O atoms from the oxidizer,
 # which is not true for this example. Therefore, the following call gives a
@@ -99,6 +115,7 @@ print(f"phi = {phi:1.3f}") # prints 2.5
 phi = gas.equivalence_ratio()
 print(f"phi = {phi:1.3f}")

+# %%
 # After computing the mixture composition for a certain equivalence ratio given
 # a fuel and mixture composition, the mixture can optionally be diluted. The
 # following function will first create a mixture with equivalence ratio 2 from pure
@@ -108,6 +125,7 @@ gas.set_equivalence_ratio(2.0, "H2:1", "O2:1", diluent="H2O", fraction={"diluent
 print(f"mole fraction of H2O = {gas['H2O'].X[0]:1.3f}") # mixture contains 30 mol-% H2O
 print(f"ratio of H2/O2: {gas['H2'].X[0] / gas['O2'].X[0]:1.3f}") # according to phi=2

+# %%
 # Another option is to specify the fuel or oxidizer fraction in the final mixture.
 # The following example creates a mixture with equivalence ratio 2 from pure
 # hydrogen and oxygen (same as above) and then dilutes it with a mixture of 50 mass-%
@@ -116,6 +134,7 @@ gas.set_equivalence_ratio(2.0, "H2", "O2", diluent="CO2:0.5,H2O:0.5",
                          fraction={"fuel":0.1}, basis="mass")
 print(f"mole fraction of H2 = {gas['H2'].Y[0]:1.3f}") # mixture contains 10 mass-% fuel

+# %%
 # To compute the equivalence ratio given a diluted mixture, a list of
 # species names can be provided which will be considered for computing phi.
 # In this example, the diluents H2O and CO2 are ignored and only H2 and O2 are
@@ -123,11 +142,13 @@ print(f"mole fraction of H2 = {gas['H2'].Y[0]:1.3f}") # mixture contains 10 mass
 phi = gas.equivalence_ratio(fuel="H2", oxidizer="O2", include_species=["H2", "O2"])
 print(f"phi = {phi:1.3f}") # prints 2

+# %%
 # If instead the diluent should be included in the computation of the equivalence ratio,
 # the mixture can be set in the following way. Assume the fuel is diluted with
 # 50 mol-% H2O:
 gas.set_equivalence_ratio(2.0, fuel="H2:0.5,H2O:0.5", oxidizer=air)

+# %%
 # This creates a mixture with the specified equivalence ratio including the diluent:
 phi = gas.equivalence_ratio(fuel="H2:0.5,H2O:0.5", oxidizer=air)
 print(f"phi = {phi:1.3f}") # prints 2
@@ -1,8 +1,12 @@
 """
-Isentropic, adiabatic flow example - calculate area ratio vs. Mach number curve
+Isentropic, adiabatic flow
+==========================
+
+Calculate area ratio vs. Mach number curve

 Requires: cantera >= 2.5.0, matplotlib >= 2.0
-Keywords: thermodynamics, compressible flow, plotting
+
+.. tags:: Python, thermodynamics, compressible flow, plotting
 """

 import cantera as ct
@@ -57,7 +61,6 @@ def isentropic(gas=None):

    return data

-
 if __name__ == "__main__":
    print(__doc__)
    data = isentropic()
@@ -1,10 +1,13 @@
 """
-Isentropic, adiabatic flow example - calculate area ratio vs. Mach number curve.
-Uses the pint library to include customized units in the calculation.
+Isentropic, adiabatic flow (with units)
+=======================================

+Isentropic, adiabatic flow example - calculate area ratio vs. Mach number curve.
+Uses the ``pint`` library to include customized units in the calculation.

 Requires: Cantera >= 3.0.0, pint
-Keywords: thermodynamics, compressible flow, units
+
+.. tags:: Python, thermodynamics, compressible flow, units
 """

 import cantera.with_units as ctu
@@ -1,14 +1,16 @@
 """
-Mixing two streams using `Quantity` objects.
+Mixing using `Quantity` objects
+===============================

-In this example, air and methane are mixed in stoichiometric proportions. This
-is a simpler, steady-state version of the example ``reactors/mix1.py``.
+In this example, air and methane are mixed in stoichiometric proportions. This is a
+simpler, steady-state version of the example :doc:`mix1.py <../reactors/mix1>`.

 Since the goal is to simulate a continuous flow system, the mixing takes place
 at constant enthalpy and pressure.

 Requires: cantera >= 2.5.0
-Keywords: thermodynamics, mixture
+
+.. tags:: Python, thermodynamics, mixture
 """

 import cantera as ct
@@ -1,9 +1,13 @@
 """
+Rankine cycle
+=============
+
 Calculate the efficiency of a Rankine vapor power cycle using a pure fluid model
 for water.

 Requires: Cantera >= 2.5.0
-Keywords: thermodynamics, thermodynamic cycle, non-ideal fluid
+
+.. tags:: Python, thermodynamics, thermodynamic cycle, non-ideal fluid
 """

 import cantera as ct
@@ -1,9 +1,13 @@
 """
+Rankine cycle (with units)
+==========================
+
 Calculate the efficiency of a Rankine vapor power cycle using a pure fluid model
 for water. Includes the units of quantities in the calculations.

 Requires: Cantera >= 3.0.0, pint
-Keywords: thermodynamics, thermodynamic cycle, non-ideal fluid, units
+
+.. tags:: Python, thermodynamics, thermodynamic cycle, non-ideal fluid, units
 """

 import cantera.with_units as ctu
@@ -1,8 +1,12 @@
 """
+Sound speeds
+============
+
 Compute the "equilibrium" and "frozen" sound speeds for a gas

 Requires: cantera >= 3.0.0
-Keywords: thermodynamics, equilibrium
+
+.. tags:: Python, thermodynamics, equilibrium
 """

 import cantera as ct
@@ -1,9 +1,13 @@
 """
-Compute the "equilibrium" and "frozen" sound speeds for a gas. Uses the pint library to
-include customized units in the calculation.
+Sound speeds (with units)
+=========================
+
+Compute the "equilibrium" and "frozen" sound speeds for a gas. Uses the ``pint`` library
+to include customized units in the calculation.

 Requires: Cantera >= 3.0.0, pint
-Keywords: thermodynamics, equilibrium, units
+
+.. tags:: Python, thermodynamics, equilibrium, units
 """

 import cantera.with_units as ctu
@@ -1,10 +1,14 @@
 """
+Vapor Dome
+==========
+
 This example generates a saturated steam table and plots the vapor dome. The
 steam table corresponds to data typically found in thermodynamic text books
 and uses the same customary units.

 Requires: Cantera >= 2.5.0, matplotlib >= 2.0, pandas >= 1.1.0, numpy >= 1.12
-Keywords: thermodynamics, non-ideal fluid, plotting
+
+.. tags:: Python, thermodynamics, non-ideal fluid, plotting
 """

 import cantera as ct
@@ -21,6 +25,7 @@ columns = ['T', 'P',
           'hf', 'hfg', 'hg',
           'sf', 'sfg', 'sg']

+# %%
 # temperatures correspond to Engineering Thermodynamics, Moran et al. (9th ed),
 # Table A-2; additional data points are added close to the critical point;
 # w.min_temp is equal to the triple point temperature
@@ -71,18 +76,21 @@ df.hf -= hf0 - pv0
 df.sg -= sf0
 df.sf -= sf0

+# %%
 # print and write saturated steam table to csv file
 print(df)
 df.to_csv('saturated_steam_T.csv', index=False)

+# %%
 # illustrate the vapor dome in a P-v diagram
 plt.semilogx(df.vf.values, df.P.values, label='Saturated liquid')
 plt.semilogx(df.vg.values, df.P.values, label='Saturated vapor')
 plt.semilogx(df.vg.values[-1], df.P.values[-1], 'o', label='Critical point')
 plt.xlabel(r'Specific volume - $v$ ($\mathrm{m^3/kg}$)')
 plt.ylabel(r'Presssure - $P$ (bar)')
-plt.legend()
+plt.legend();

+# %%
 # illustrate the vapor dome in a T-s diagram
 plt.figure()
 plt.plot(df.sf.values, df['T'].values, label='Saturated liquid')
@@ -0,0 +1,2 @@
+Transport
+---------
@@ -1,13 +1,15 @@
 """
-Calculate transport properties in a porous medium using the dusty gas transport model.
+Porous media transport using the dusty gas model
+================================================

-The Dusty Gas model is a multicomponent transport model for gas transport
-through the pores of a stationary porous medium. This example shows how to
-create a transport manager that implements the Dusty Gas model and use it to
-compute the multicomponent diffusion coefficients and thermal conductivity.
+The dusty gas model is a multicomponent transport model for gas transport through the
+pores of a stationary porous medium. This example shows how to create a
+:ct:`DustyGasTransport` transport manager and use it to compute the multicomponent
+diffusion coefficients and thermal conductivity.

 Requires:  cantera >= 2.6.0
-Keywords: transport, multicomponent transport
+
+.. tags:: Python, transport, multicomponent transport
 """

 import cantera as ct
@@ -1,5 +1,8 @@
 """
-This example demonstrates how Cantera can be used with the 'multiprocessing'
+Parallelizing transport property calculations
+=============================================
+
+This example demonstrates how Cantera can be used with the `multiprocessing`
 module.

 Because Cantera Python objects are built on top of C++ objects which cannot be
@@ -9,7 +12,8 @@ do this is by storing the objects in (module) global variables, which are
 initialized once per worker process.

 Requires: cantera >= 2.5.0
-Keywords: transport, benchmarking, parallel computing
+
+.. tags:: Python, transport, benchmarking, parallel computing
 """

 import multiprocessing