From 1be7f54df7369b9d0e4e18fdafe8a833e9b42844 Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Thu, 28 Dec 2023 23:08:33 +0100 Subject: [PATCH 1/7] Allows sorting of sections by their title and a custom key function --- autodocsumm/__init__.py | 8 +++++++- docs/conf_settings.rst | 9 +++++++++ tests/test-root/conf.py | 2 ++ tests/test_autodocsumm.py | 9 +++++++++ 4 files changed, 27 insertions(+), 1 deletion(-) diff --git a/autodocsumm/__init__.py b/autodocsumm/__init__.py index e1cc854..bc61420 100755 --- a/autodocsumm/__init__.py +++ b/autodocsumm/__init__.py @@ -270,7 +270,12 @@ 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 + + if callable(self.env.config.autodocsumm_section_sorter): + return {k: documenters[k] for k in sorted(documenters, key=self.env.config.autodocsumm_section_sorter)} + else: + return documenters + def add_autosummary(self, relative_ref_paths=False): """Add the autosammary table of this documenter. @@ -656,6 +661,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} diff --git a/docs/conf_settings.rst b/docs/conf_settings.rst index 225dc04..a2b0bd7 100644 --- a/docs/conf_settings.rst +++ b/docs/conf_settings.rst @@ -135,3 +135,12 @@ 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 + + This can be set with a callable that is passed to :func:`sorted` as key + argument to sort the the summary sections by their name. Example usage for + an alphanumerical order:: + + autodocsumm_section_sorter = lambda s: s diff --git a/tests/test-root/conf.py b/tests/test-root/conf.py index d62ba83..942beda 100644 --- a/tests/test-root/conf.py +++ b/tests/test-root/conf.py @@ -24,6 +24,8 @@ autodata_content = 'both' +autodocsumm_section_sorter = lambda a: a + def member_filter(app, what, name, obj, skip, options): import dummy diff --git a/tests/test_autodocsumm.py b/tests/test_autodocsumm.py index b2b2811..572fbbf 100644 --- a/tests/test_autodocsumm.py +++ b/tests/test_autodocsumm.py @@ -41,6 +41,10 @@ def get_html(app, fname): return f.read() +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") @@ -377,6 +381,11 @@ def test_module_submodule(self, app): assert re.findall(r'.*href="#dummy_submodule\.submodule2' r'\.SubmoduleClass2\.func2".*', 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`.""" From 8da458ab79e014aa70c28e8a60aed923f84cddaf Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Thu, 28 Dec 2023 23:10:16 +0100 Subject: [PATCH 2/7] Removes source's encoding declaration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit with Python 3 all is unicode 💜 --- docs/conf.py | 2 -- tests/test-root/conf.py | 1 - tests/test-root/dummy.py | 1 - tests/test-root/dummy_title.py | 1 - 4 files changed, 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3b59b3d..f793772 100644 --- a/docs/conf.py +++ b/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. # diff --git a/tests/test-root/conf.py b/tests/test-root/conf.py index 942beda..29292b1 100644 --- a/tests/test-root/conf.py +++ b/tests/test-root/conf.py @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- import sys import sphinx sys.path.insert(0, '.') diff --git a/tests/test-root/dummy.py b/tests/test-root/dummy.py index cc121d0..36be801 100644 --- a/tests/test-root/dummy.py +++ b/tests/test-root/dummy.py @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- """ Module for testing the autodocsumm diff --git a/tests/test-root/dummy_title.py b/tests/test-root/dummy_title.py index 6cab295..e5200e4 100644 --- a/tests/test-root/dummy_title.py +++ b/tests/test-root/dummy_title.py @@ -1,4 +1,3 @@ -# -*- coding: utf-8 -*- """ Module for testing the autodocsumm ---------------------------------- From 444b5a9065e40ddf7ebc0e48967863c8460c83eb Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Thu, 28 Dec 2023 23:11:27 +0100 Subject: [PATCH 3/7] Simplifies a test helper --- tests/test_autodocsumm.py | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/tests/test_autodocsumm.py b/tests/test_autodocsumm.py index 572fbbf..a06326f 100644 --- a/tests/test_autodocsumm.py +++ b/tests/test_autodocsumm.py @@ -47,13 +47,7 @@ def get_soup(app, fname): 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: From 3693a603817980d778a2809fa5d58b8d58036b4f Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Thu, 28 Dec 2023 23:15:26 +0100 Subject: [PATCH 4/7] Employs pathlib interface in the tests --- tests/test_autodocsumm.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/tests/test_autodocsumm.py b/tests/test_autodocsumm.py index a06326f..1fdcb59 100644 --- a/tests/test_autodocsumm.py +++ b/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,8 +37,7 @@ 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): From 91b63e0cfc772b858fce96c9b9a2451ef518bd8a Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Fri, 29 Dec 2023 13:41:20 +0100 Subject: [PATCH 5/7] Allows passing True as autodocsumm_section_sorter for simple sorting --- autodocsumm/__init__.py | 7 +++++-- docs/conf_settings.rst | 14 +++++++++----- tests/test-root/conf.py | 2 +- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/autodocsumm/__init__.py b/autodocsumm/__init__.py index bc61420..5808308 100755 --- a/autodocsumm/__init__.py +++ b/autodocsumm/__init__.py @@ -271,8 +271,11 @@ def get_grouped_documenters(self, all_members=False): documenters.setdefault(section, []).append(e) self.options.update(options_save) - if callable(self.env.config.autodocsumm_section_sorter): - return {k: documenters[k] for k in sorted(documenters, key=self.env.config.autodocsumm_section_sorter)} + 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 diff --git a/docs/conf_settings.rst b/docs/conf_settings.rst index a2b0bd7..70a85ce 100644 --- a/docs/conf_settings.rst +++ b/docs/conf_settings.rst @@ -139,8 +139,12 @@ Configuration values and events .. confval:: autodocsumm_section_sorter - This can be set with a callable that is passed to :func:`sorted` as key - argument to sort the the summary sections by their name. Example usage for - an alphanumerical order:: - - autodocsumm_section_sorter = lambda s: s + 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: + + sections_order = ("Public methods", "Attributes", "Private methods") + autodocsumm_section_sorter = lambda title: sections_order.index(title) diff --git a/tests/test-root/conf.py b/tests/test-root/conf.py index 29292b1..a9b3df0 100644 --- a/tests/test-root/conf.py +++ b/tests/test-root/conf.py @@ -23,7 +23,7 @@ autodata_content = 'both' -autodocsumm_section_sorter = lambda a: a +autodocsumm_section_sorter = True def member_filter(app, what, name, obj, skip, options): From b1e894767fa85541fee02df39a48c867ba173073 Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Fri, 29 Dec 2023 14:08:42 +0100 Subject: [PATCH 6/7] Amends an example usage for autodocsumm_section_sorter --- docs/conf_settings.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/conf_settings.rst b/docs/conf_settings.rst index 70a85ce..0d4c30e 100644 --- a/docs/conf_settings.rst +++ b/docs/conf_settings.rst @@ -148,3 +148,10 @@ Configuration values and events 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: + + section_weights = {"Attributes": 100, "Constructors": -100} + autodocsumm_section_sorter = lambda title: sections_weights.get(title, 0) From ea71375b103a72671d2b50b9253729d9c4616d69 Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Thu, 4 Jan 2024 11:49:03 +0100 Subject: [PATCH 7/7] docs: Adds missing directives Co-authored-by: Philipp S. Sommer --- docs/conf_settings.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf_settings.rst b/docs/conf_settings.rst index 0d4c30e..7f3e923 100644 --- a/docs/conf_settings.rst +++ b/docs/conf_settings.rst @@ -146,6 +146,8 @@ Configuration values and events 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) @@ -153,5 +155,7 @@ Configuration values and events 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)