[Doc] Adjust example docstrings to get better automatic summaries

interfaces/cython/cantera/examples/onedim/flame_fixed_T.py

@@ -1,6 +1,6 @@
 """
-FIXED_T_FLAME - A burner-stabilized, premixed methane/air flat flame with
-multicomponent transport properties and a specified temperature profile.
+A burner-stabilized, premixed methane/air flat flame with multicomponent
+transport properties and a specified temperature profile.
 """
 
 import cantera as ct

interfaces/cython/cantera/examples/reactors/combustor.py

@@ -1,10 +1,12 @@
 """
 A combustor. Two separate stream - 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.
+300 K and 1 atm flow into an adiabatic combustor where they mix and burn.
+
+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.
 """
 
 import math

interfaces/cython/cantera/examples/reactors/periodic_cstr.py

@@ -1,7 +1,7 @@
 """
-Periodic CSTR
+This example illustrates a continuously stirred tank reactor (CSTR) with steady
+inputs but periodic interior state.
 
-This example illustrates a CSTR with steady inputs but periodic interior state.
 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

interfaces/cython/cantera/examples/reactors/piston.py

@@ -1,4 +1,6 @@
 """
+Two reactors separated by a piston
+
 Gas 1: a stoichiometric H2/O2/Ar mixture
 Gas 2: a wet CO/O2 mixture
 

interfaces/cython/cantera/examples/reactors/reactor2.py

@@ -1,4 +1,6 @@
 """
+Two reactors connected with a piston, with heat loss to the environment
+
 This script simulates the following situation. A closed cylinder with volume 2
 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

interfaces/cython/cantera/examples/surface_chemistry/diamond_cvd.py

@@ -1,5 +1,5 @@
 """
-A CVD example.
+A CVD example simulating growth of a diamond film
 
 This example computes the growth rate of a diamond film according to a
 simplified version of a particular published growth mechanism (see file

interfaces/cython/cantera/examples/surface_chemistry/sofc.py

@@ -1,12 +1,12 @@
 """
-SOFC
+A simple model of a solid oxide fuel cell.
 
-This script implements a simple model of a solid oxide fuel cell. Unlike most
-SOFC models, however, it does not use semi-empirical Butler-Volmer kinetics
-for the charge transfer reactions, but uses elementary, reversible reactions
-obeying mass-action kinetics for all reactions, including charge 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.
+Unlike most SOFC models, this model does not use semi-empirical Butler- Volmer
+kinetics for the charge transfer reactions, but uses elementary, reversible
+reactions obeying mass-action kinetics for all reactions, including charge
+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.cti, are not to be
 relied upon for a real SOFC simulation! They are meant to illustrate only how

interfaces/cython/cantera/examples/thermo/isentropic.py

@@ -1,3 +1,7 @@
+"""
+Isentropic, adiabatic flow example - calculate area ratio vs. Mach number curve
+"""
+
 import cantera as ct
 import math
 import numpy as np
@@ -13,16 +17,12 @@ def soundspeed(gas):
 
 def isentropic(gas=None):
     """
-    ISENTROPIC  isentropic, adiabatic flow example
-
-    In this example, the area ratio vs. Mach number curve is computed. If a
-    gas object is supplied, it will be used for the calculations, with the
+    In this example, the area ratio vs. Mach number curve is computed. If a gas
+    object is supplied, it will be used for the calculations, with the
     stagnation state given by the input gas state. Otherwise, the calculations
-    will be done for a 10:1 hydrogen/nitrogen mixture with stagnation T0 =
-    1200 K, P0 = 10 atm.
-
+    will be done for a 10:1 hydrogen/nitrogen mixture with stagnation T0 = 1200
+    K, P0 = 10 atm.
     """
-
     if gas is None:
         gas = ct.Solution('gri30.xml')
         gas.TPX = 1200.0, 10.0*ct.one_atm, 'H2:1,N2:0.1'

interfaces/cython/cantera/examples/thermo/sound_speed.py

@@ -1,3 +1,7 @@
+"""
+Compute the "equilibrium" and "frozen" sound speeds for a gas
+"""
+
 import cantera as ct
 import math
 

samples/matlab/catcomb.m

@@ -1,4 +1,4 @@
-% CATCOMB  -- Catalytic combustion on platinum.
+% Catalytic combustion of a stagnation flow on a platinum surface
 %
 % 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