Merge pull request #93 from funkyfuture/sorted_sections

An option to sort sections

Author: Chilipp

autodocsumm/__init__.py

@@ -270,7 +270,15 @@ def get_grouped_documenters(self, all_members=False):
             if not use_sections or section in use_sections:
                 documenters.setdefault(section, []).append(e)
         self.options.update(options_save)
-        return documenters
+
+        sort_option = self.env.config.autodocsumm_section_sorter
+        if sort_option is True:
+            return {k: documenters[k] for k in sorted(documenters)}
+        elif callable(sort_option):
+            return {k: documenters[k] for k in sorted(documenters, key=sort_option)}
+        else:
+            return documenters
+
 
     def add_autosummary(self, relative_ref_paths=False):
         """Add the autosammary table of this documenter.
@@ -656,6 +664,7 @@ def setup(app):
     app.add_config_value('autodata_content', 'class', True)
     app.add_config_value('document_data', True, True)
     app.add_config_value('not_document_data', [], True)
+    app.add_config_value('autodocsumm_section_sorter', None, True)
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
 
 

docs/conf.py

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # autodocsumm documentation build configuration file, created by
 # sphinx-quickstart on Mon Jul 20 18:01:33 2015.
 #

docs/conf_settings.rst

@@ -135,3 +135,27 @@ Configuration values and events
     To exclude the string representation of specific data objects. You may
     provide a list of fully qualified object names (e.g. in the form of
     ``'zipfile.ZipFile'``) or ``True`` or ``False``
+
+
+.. confval:: autodocsumm_section_sorter
+
+   When ``True`` the summarizing sections will be sorted alphanumerically by
+   their section title. Alternatively a callable can be set that is passed to
+   :func:`sorted` as key argument to sort the the summary sections by their
+   name.
+   The default value is ``None``.
+   Example usage with a tuple that defines an arbitrary order:
+
+   .. code-block:: python
+
+       sections_order = ("Public methods", "Attributes", "Private methods")
+       autodocsumm_section_sorter = lambda title: sections_order.index(title)
+
+   An example for cases that only ensures that "Constructors" are always listed
+   first and "Attributes" while not failing when encountering undefined section
+   weights:
+
+   .. code-block:: python
+
+       section_weights = {"Attributes": 100, "Constructors": -100}
+       autodocsumm_section_sorter = lambda title: sections_weights.get(title, 0)

tests/test-root/conf.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 import sys
 import sphinx
 sys.path.insert(0, '.')
@@ -24,6 +23,8 @@
 
 autodata_content = 'both'
 
+autodocsumm_section_sorter = True
+
 
 def member_filter(app, what, name, obj, skip, options):
     import dummy

tests/test-root/dummy.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """
 Module for testing the autodocsumm
 

tests/test-root/dummy_title.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 """
 Module for testing the autodocsumm
 ----------------------------------

tests/test_autodocsumm.py

@@ -17,7 +17,7 @@
 See the License for the specific language governing permissions and
 limitations under the License.
 """
-import os.path as osp
+from pathlib import Path
 import re
 import bs4
 import pytest
@@ -37,19 +37,16 @@ def in_between(full, sub, s0, *others):
 
 
 def get_html(app, fname):
-    with open(osp.join(str(app.outdir), fname)) as f:
-        return f.read()
+    return (Path(app.outdir) / fname).read_text()
+
+
+def get_soup(app, fname):
+    return bs4.BeautifulSoup(get_html(app, fname), 'html.parser')
 
 
 def in_autosummary(what, html) -> bool:
     soup = bs4.BeautifulSoup(html, "html.parser")
-    autosummaries = soup("table")
-    found = False
-    for tag in autosummaries:
-        if tag.find_all("span", string=what):
-            found = True
-            break
-    return found
+    return any(tag.find_all("span", string=what) for tag in soup("table"))
 
 
 class TestAutosummaryDocumenter:
@@ -377,6 +374,11 @@ def test_module_submodule(self, app):
         assert re.findall(r'<td>.*href="#dummy_submodule\.submodule2'
                           r'\.SubmoduleClass2\.func2".*</td>', html)
 
+    def test_sorted_sections(self, app):
+        soup = get_soup(app, 'test_autoclasssumm_some_sections.html')
+        sections = soup.select("p strong")
+        assert [s.string[:-1] for s in sections] == ["Attributes", "DummySection"]
+
 
 class TestAutoDocSummDirective:
     """Test case for the :class:`autodocsumm.AutoDocSummDirective`."""