[Doc] Include summaries of each example in index of Matlab examples

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')

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)

doc/sphinx/matlab/example-script.rst.in

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _matlab-example-@script_name@:
 
 @script_name@

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@