ENH: Add ExampleTitleSortKey

larsoner · larsoner · commit d7e00c20f70e · 2017-08-02T15:45:32.000-06:00
diff --git a/sphinx_gallery/sorting.py b/sphinx_gallery/sorting.py
@@ -100,3 +100,19 @@ class FileNameSortKey(_SortKey):
 
     def __call__(self, filename):
         return filename
+
+
+class ExampleTitleSortKey(_SortKey):
+    """Sort examples in src_dir by example title.
+
+    Parameters
+    ----------
+    src_dir : str
+        The source directory.
+    """
+
+    def __call__(self, filename):
+        src_file = os.path.normpath(os.path.join(self.src_dir, filename))
+        _, script_blocks = split_code_and_text_blocks(src_file)
+        # title should be the second line of the first script_blocks entry
+        return script_blocks[0][1].strip().split('\n')[1]
diff --git a/sphinx_gallery/tests/test_gen_gallery.py b/sphinx_gallery/tests/test_gen_gallery.py
@@ -200,7 +200,7 @@ def test_example_sorting_default(config_app):
     'within_subsection_order': FileSizeSortKey,
 }""")
 def test_example_sorting_filesize(config_app):
-    """Test sorting of examples by default key (number of code lines)."""
+    """Test sorting of examples by filesize."""
     _check_order(config_app, 'filesize')
 
 
@@ -214,5 +214,19 @@ def test_example_sorting_filesize(config_app):
     'within_subsection_order': FileNameSortKey,
 }""")
 def test_example_sorting_filename(config_app):
-    """Test sorting of examples by default key (number of code lines)."""
+    """Test sorting of examples by filename."""
     _check_order(config_app, 'filename')
+
+
+@pytest.mark.conf_file(content="""
+import sphinx_gallery
+from sphinx_gallery.sorting import ExampleTitleSortKey
+extensions = ['sphinx_gallery.gen_gallery']
+sphinx_gallery_conf = {
+    'examples_dirs': 'src',
+    'gallery_dirs': 'ex',
+    'within_subsection_order': ExampleTitleSortKey,
+}""")
+def test_example_sorting_title(config_app):
+    """Test sorting of examples by title."""
+    _check_order(config_app, 'title')
