[Doc] Add all Python examples to the Sphinx docs

.gitignore

@@ -34,3 +34,4 @@ config.log
 *.gcno
 coverage/
 coverage.info
+doc/sphinx/cython/examples/*.rst

doc/SConscript

@@ -21,4 +21,17 @@ if localenv['sphinx_docs']:
         'sphinx/conf.py',
         '${sphinx_cmd} -b html -d ${SPHINXBUILD}/doctrees ${SPHINXSRC} ${SPHINXBUILD}/html'))
 
+    # Python examples: Create individual documentation pages with the source
+    # for each example
+    example_root = Dir('#interfaces/cython/cantera/examples').abspath
+    for subdir in subdirs(example_root):
+        for f in mglob(env, pjoin(example_root, subdir), 'py'):
+            tmpenv = env.Clone()
+            tmpenv['script_name'] = f.name
+            tmpenv['script_path'] = '../../../../interfaces/cython/cantera/examples/%s/%s' % (subdir, f.name)
+            b = tmpenv.SubstFile('#doc/sphinx/cython/examples/%s_%s.rst' % (subdir, f.name[:-3]),
+                                 '#doc/sphinx/cython/examples/example-script.rst.in')
+            build(b)
+            localenv.Depends(sphinxdocs, b)
+
     localenv.AlwaysBuild(sphinxdocs)

doc/sphinx/cython/examples.rst

@@ -0,0 +1,62 @@
+.. _sec-cython-examples:
+
+.. py:currentmodule:: cantera
+
+Index of Examples
+=================
+
+This is an index of the examples included with the Cantera Python module. They
+can be found in the `examples` subdirectory of the Cantera Python module's
+installation directory. To determine the location of this directory, run the following in your Python interpreter::
+
+    import cantera.examples
+    print(cantera.examples.__path__)
+
+Thermodynamics
+--------------
+.. toctree::
+   :glob:
+
+   examples/thermo*
+
+Kinetics
+--------
+.. toctree::
+   :glob:
+
+   examples/kinetics*
+
+Transport
+---------
+.. toctree::
+   :glob:
+
+   examples/transport*
+
+Reactor Networks
+----------------
+.. toctree::
+   :glob:
+
+   examples/reactors*
+
+One-dimensional Flames
+----------------------
+.. toctree::
+   :glob:
+
+   examples/onedim*
+
+Multiphase Mixtures
+-------------------
+.. toctree::
+   :glob:
+
+   examples/multiphase*
+
+Surface Chemistry
+-----------------
+.. toctree::
+   :glob:
+
+   examples/surface_chemistry*

doc/sphinx/cython/examples/example-script.rst.in

@@ -0,0 +1,4 @@
+@script_name@
+=======================================================================
+
+.. literalinclude:: @script_path@

doc/sphinx/cython/index.rst

@@ -17,3 +17,4 @@ Contents:
    zerodim
    onedim
    constants
+   examples

interfaces/cython/SConscript

@@ -204,10 +204,8 @@ if localenv['python_package'] == 'new':
             subprocess.call(['3to2', '--no-diff', '-n', '-w','-x', 'str',
                              '-x', 'open', target[0].abspath])
 
-        for subdir in os.listdir('cantera/examples'):
+        for subdir in subdirs('cantera/examples'):
             dirpath = pjoin('cantera', 'examples', subdir)
-            if not os.path.isdir(dirpath):
-                continue
             for filename in os.listdir(dirpath):
                 if not filename.endswith('.py'):
                     continue

site_scons/buildutils.py

@@ -12,6 +12,7 @@ import shutil
 import itertools
 
 import SCons.Errors
+import SCons
 from distutils.version import LooseVersion
 import distutils.sysconfig
 
@@ -405,6 +406,13 @@ def psplit(s):
     return path
 
 
+def subdirs(path):
+    """ Get the subdirectories of a specified directory """
+    for subdir in os.listdir(path):
+        dirpath = pjoin(path, subdir)
+        if os.path.isdir(dirpath):
+            yield subdir
+
 def stripDrive(s):
     """
     Remove a Windows drive letter specification from a path.