From 0c1eb4cd892b466b3ae69e43fcf592fab8c5521e Mon Sep 17 00:00:00 2001
From: Ray Speth <speth@mit.edu>
Date: Fri, 14 Oct 2016 16:58:24 -0400
Subject: [PATCH] [Doc] Include summaries of each example in index of Matlab
 examples

---
 SConstruct                                    |  2 +-
 doc/SConscript                                | 38 ++++++++++++++++---
 doc/sphinx/matlab/example-script.rst.in       |  2 +
 .../matlab/{examples.rst => examples.rst.in}  |  9 +----
 4 files changed, 37 insertions(+), 14 deletions(-)
 rename doc/sphinx/matlab/{examples.rst => examples.rst.in} (70%)

diff --git a/SConstruct b/SConstruct
index f15d257f3..9f15c6166 100644
--- a/SConstruct
+++ b/SConstruct
@@ -67,7 +67,7 @@ if 'clean' in COMMAND_LINE_TARGETS:
     removeFile('interfaces/python_minimal/setup.py')
     removeFile('config.log')
     removeDirectory('doc/sphinx/matlab/examples')
-    removeDirectory('doc/sphinx/matlab/tutorials')
+    removeFile('doc/sphinx/matlab/examples.rst')
     removeDirectory('doc/sphinx/matlab/code-docs')
     removeDirectory('doc/sphinx/cython/examples')
     removeFile('doc/sphinx/cython/examples.rst')
diff --git a/doc/SConscript b/doc/SConscript
index cb35b47db..896b8ad65 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -24,6 +24,21 @@ def extract_python_docstring(pyfile, summary_only=True):
 
     return doc
 
+def extract_matlab_summary(mfile):
+    """ Returns a one-line summary comment from a .m file """
+    doc = ''
+    with open(mfile) as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith('%'):
+                doc = line.strip('%').strip()
+            if doc:
+                break
+    name = os.path.basename(mfile)[:-2].replace('_', ' ')
+    if doc.lower().replace('_', ' ').startswith(name):
+        doc = doc[len(name):].strip()
+    return doc
+
 
 # Set up functions to pseudo-autodoc the MATLAB toolbox
 def extract_matlab_docstring(mfile, level):
@@ -254,17 +269,28 @@ if localenv['sphinx_docs']:
 
     # Matlab examples: create individual documentation pages with the source
     # for each example
+    examples = []
+    tutorials = []
     for f in mglob(env, '#samples/matlab', 'm'):
         tmpenv = env.Clone()
         tmpenv['script_name'] = f.name
         tmpenv['script_path'] = '../../../../samples/matlab/%s' % f.name
-        if f.name.startswith('tut'):
-            b = tmpenv.SubstFile('#doc/sphinx/matlab/tutorials/%s.rst' % f.name[:-2],
-                                 '#doc/sphinx/matlab/example-script.rst.in')
-        else:
-            b = tmpenv.SubstFile('#doc/sphinx/matlab/examples/%s.rst' % f.name[:-2],
-                                 '#doc/sphinx/matlab/example-script.rst.in')
+        b = tmpenv.SubstFile('#doc/sphinx/matlab/examples/%s.rst' % f.name[:-2],
+                             '#doc/sphinx/matlab/example-script.rst.in')
         build(b)
         localenv.Depends(sphinxdocs, b)
+        summary = [':doc:`{0} <examples/{1}>`:'.format(f.name, f.name[:-2]),
+                   extract_matlab_summary(f.abspath),
+                   '']
+        if f.name.startswith('tut'):
+            tutorials.extend(summary)
+        else:
+            examples.extend(summary)
 
+    localenv['matlab_tutorials'] = '\n'.join(tutorials)
+    localenv['matlab_examples'] = '\n'.join(examples)
+    b = localenv.SubstFile('#doc/sphinx/matlab/examples.rst',
+                           '#doc/sphinx/matlab/examples.rst.in')
+    build(b)
+    localenv.Depends(sphinxdocs, b)
     localenv.AlwaysBuild(sphinxdocs)
diff --git a/doc/sphinx/matlab/example-script.rst.in b/doc/sphinx/matlab/example-script.rst.in
index 1a6fe3cac..aa4d452f6 100644
--- a/doc/sphinx/matlab/example-script.rst.in
+++ b/doc/sphinx/matlab/example-script.rst.in
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _matlab-example-@script_name@:
 
 @script_name@
diff --git a/doc/sphinx/matlab/examples.rst b/doc/sphinx/matlab/examples.rst.in
similarity index 70%
rename from doc/sphinx/matlab/examples.rst
rename to doc/sphinx/matlab/examples.rst.in
index 44a912c7f..0c0534ab8 100644
--- a/doc/sphinx/matlab/examples.rst
+++ b/doc/sphinx/matlab/examples.rst.in
@@ -7,15 +7,10 @@ This is an index of the examples included with the Cantera Matlab Toolbox.
 
 Tutorials
 ---------
-.. toctree::
-   :glob:
 
-   tutorials/*
+@matlab_tutorials@
 
 Examples
 --------
 
-.. toctree::
-   :glob:
-
-   examples/*
+@matlab_examples@