From 2b016903019eef954dc9b468f64929f8ac3d7e44 Mon Sep 17 00:00:00 2001 From: Marten Henric van Kerkwijk Date: Thu, 18 Apr 2024 19:41:33 -0400 Subject: [PATCH] Ensure sort is done also in automodsumm file writing Signed-off-by: nstarman # Conflicts: # sphinx_automodapi/automodsumm.py --- sphinx_automodapi/automodsumm.py | 15 ++++++++++++--- sphinx_automodapi/tests/test_automodsumm.py | 14 +++++++++++++- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/sphinx_automodapi/automodsumm.py b/sphinx_automodapi/automodsumm.py index 7ff388b..2ddb478 100644 --- a/sphinx_automodapi/automodsumm.py +++ b/sphinx_automodapi/automodsumm.py @@ -46,6 +46,12 @@ in the generated documentation. The flags ``:inherited-members:`` or ``:no-inherited-members:`` allows overrriding this global setting. + * ``:sort:`` + If the module contains ``__all__``, sort the module's objects + alphabetically (if ``__all__`` is not present, the objects are found + using `dir`, which always gives a sorted list). + + This extension also adds three sphinx configuration options: * ``automodsumm_writereprocessed`` @@ -381,12 +387,12 @@ def automodsumm_to_autosummary_lines(fn, app): opssecs, remainders)): allindent = i1 + (' ' if i2 is None else i2) - # filter out functions-only, classes-only, and ariables-only + # filter out functions-only, classes-only, variables-only, and sort # options if present. oplines = ops.split('\n') toskip = [] allowedpkgnms = [] - funcsonly = clssonly = varsonly = False + funcsonly = clssonly = varsonly = sort = False for i, ln in reversed(list(enumerate(oplines))): if ':functions-only:' in ln: funcsonly = True @@ -403,6 +409,9 @@ def automodsumm_to_autosummary_lines(fn, app): if ':allowed-package-names:' in ln: allowedpkgnms.extend(_str_list_converter(ln.replace(':allowed-package-names:', ''))) del oplines[i] + if ':sort:' in ln: + sort = True + del oplines[i] if [funcsonly, clssonly, varsonly].count(True) > 1: msg = ('Defined more than one of functions-only, classes-only, ' 'and variables-only. Skipping this directive.') @@ -420,7 +429,7 @@ def automodsumm_to_autosummary_lines(fn, app): newlines.extend(oplines) ols = True if len(allowedpkgnms) == 0 else allowedpkgnms - for nm, fqn, obj in zip(*find_mod_objs(modnm, onlylocals=ols)): + for nm, fqn, obj in zip(*find_mod_objs(modnm, onlylocals=ols, sort=sort)): if nm in toskip: continue if funcsonly and not inspect.isroutine(obj): diff --git a/sphinx_automodapi/tests/test_automodsumm.py b/sphinx_automodapi/tests/test_automodsumm.py index e755139..3922faa 100644 --- a/sphinx_automodapi/tests/test_automodsumm.py +++ b/sphinx_automodapi/tests/test_automodsumm.py @@ -205,6 +205,14 @@ def test_ams_cython(tmpdir, cython_testpackage): # noqa # ============================================================================= +CLASS_RST = """ +:orphan: + +.. currentmodule:: {mod} + +.. autoclass:: {cls} +""".strip() + sorted_str = """ Before @@ -229,7 +237,11 @@ def test_sort(tmpdir): with open(tmpdir.join("index.rst").strpath, "w") as f: f.write(sorted_str) - write_api_files_to_tmpdir(tmpdir) + apidir = tmpdir.mkdir('api') + mod = 'sphinx_automodapi.tests.example_module.classes' + for cls in "Spam", "Egg": + with open(apidir.join(f'{mod}.{cls}.rst').strpath, 'w') as f: + f.write(CLASS_RST.format(mod=mod, cls=cls)) run_sphinx_in_tmpdir(tmpdir)