From a35a0cb51034a2256b8bab39c94c6e9f5748dc55 Mon Sep 17 00:00:00 2001
From: Ray Speth <speth@mit.edu>
Date: Fri, 14 Oct 2016 11:29:44 -0400
Subject: [PATCH] [Doc] Include summaries of each example in index of Python
 examples

---
 .gitignore                                    |  1 +
 SConstruct                                    |  1 +
 doc/SConscript                                | 32 ++++++++++++++++++-
 doc/sphinx/cython/example-script.rst.in       |  2 ++
 .../cython/{examples.rst => examples.rst.in}  | 28 ++++------------
 5 files changed, 42 insertions(+), 22 deletions(-)
 rename doc/sphinx/cython/{examples.rst => examples.rst.in} (67%)

diff --git a/.gitignore b/.gitignore
index fd1651b13..b1a312982 100644
--- a/.gitignore
+++ b/.gitignore
@@ -37,6 +37,7 @@ config.log
 coverage/
 coverage.info
 doc/sphinx/cython/examples
+doc/sphinx/cython/examples.rst
 doc/sphinx/matlab/examples/
 doc/sphinx/matlab/tutorials/
 doc/sphinx/matlab/code-docs/
diff --git a/SConstruct b/SConstruct
index 68a50dd1e..f15d257f3 100644
--- a/SConstruct
+++ b/SConstruct
@@ -70,6 +70,7 @@ if 'clean' in COMMAND_LINE_TARGETS:
     removeDirectory('doc/sphinx/matlab/tutorials')
     removeDirectory('doc/sphinx/matlab/code-docs')
     removeDirectory('doc/sphinx/cython/examples')
+    removeFile('doc/sphinx/cython/examples.rst')
     removeDirectory('interfaces/cython/Cantera.egg-info')
     removeDirectory('interfaces/python_minimal/Cantera_minimal_.egg-info')
     for name in os.listdir('interfaces/cython/cantera/data/'):
diff --git a/doc/SConscript b/doc/SConscript
index 6a6007140..cb35b47db 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -1,4 +1,5 @@
 from buildutils import *
+import ast
 
 Import('env', 'build', 'install')
 
@@ -7,6 +8,23 @@ localenv = env.Clone()
 from collections import namedtuple
 Page = namedtuple('Page', ['name', 'title', 'objects'])
 
+def extract_python_docstring(pyfile, summary_only=True):
+    """ Returns the docstring from a Python script """
+    with open(pyfile) as f:
+        mod = ast.parse(f.read())
+    doc = ''
+    for node in mod.body:
+        if isinstance(node, ast.Expr) and isinstance(node.value, ast.Str):
+            doc = node.value.s
+
+    doc = doc.strip()
+
+    if summary_only:
+        doc = doc.split('\n\n')[0]
+
+    return doc
+
+
 # Set up functions to pseudo-autodoc the MATLAB toolbox
 def extract_matlab_docstring(mfile, level):
     """
@@ -112,15 +130,27 @@ if localenv['sphinx_docs']:
     # Python examples: Create individual documentation pages with the source
     # for each example
     example_root = Dir('#interfaces/cython/cantera/examples').abspath
+    indexenv = env.Clone()
     for subdir in subdirs(example_root):
+        summaries = []
         for f in mglob(env, pjoin(example_root, subdir), 'py'):
+            docname = 'examples/{0}_{1}'.format(subdir, f.name[:-3])
+            summaries.append(':doc:`{0} <{1}>`:'.format(f.name, docname))
+            summaries.append(extract_python_docstring(f.abspath))
+            summaries.append('')
+
             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]),
+            b = tmpenv.SubstFile('#doc/sphinx/cython/{0}.rst'.format(docname),
                                  '#doc/sphinx/cython/example-script.rst.in')
             build(b)
             localenv.Depends(sphinxdocs, b)
+        indexenv['python_{0}_examples'.format(subdir)] = '\n'.join(summaries)
+    b = indexenv.SubstFile('#doc/sphinx/cython/examples.rst',
+                           '#doc/sphinx/cython/examples.rst.in')
+    build(b)
+    localenv.Depends(sphinxdocs, b)
 
     # Create a list of MATLAB classes to document. This uses the NamedTuple
     # structure defined at the top of the file. The @Data and @Utilities
diff --git a/doc/sphinx/cython/example-script.rst.in b/doc/sphinx/cython/example-script.rst.in
index 259732feb..786f15662 100644
--- a/doc/sphinx/cython/example-script.rst.in
+++ b/doc/sphinx/cython/example-script.rst.in
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _py-example-@script_name@:
 
 @script_name@
diff --git a/doc/sphinx/cython/examples.rst b/doc/sphinx/cython/examples.rst.in
similarity index 67%
rename from doc/sphinx/cython/examples.rst
rename to doc/sphinx/cython/examples.rst.in
index 31f6d3e8f..58ef6829f 100644
--- a/doc/sphinx/cython/examples.rst
+++ b/doc/sphinx/cython/examples.rst.in
@@ -14,49 +14,35 @@ installation directory. To determine the location of this directory, run the fol
 
 Thermodynamics
 --------------
-.. toctree::
-   :glob:
 
-   examples/thermo*
+@python_thermo_examples@
 
 Kinetics
 --------
-.. toctree::
-   :glob:
 
-   examples/kinetics*
+@python_kinetics_examples@
 
 Transport
 ---------
-.. toctree::
-   :glob:
 
-   examples/transport*
+@python_transport_examples@
 
 Reactor Networks
 ----------------
-.. toctree::
-   :glob:
 
-   examples/reactors*
+@python_reactors_examples@
 
 One-dimensional Flames
 ----------------------
-.. toctree::
-   :glob:
 
-   examples/onedim*
+@python_onedim_examples@
 
 Multiphase Mixtures
 -------------------
-.. toctree::
-   :glob:
 
-   examples/multiphase*
+@python_multiphase_examples@
 
 Surface Chemistry
 -----------------
-.. toctree::
-   :glob:
 
-   examples/surface_chemistry*
+@python_surface_chemistry_examples@