From 4352991338c187ab20d9bbf7ec895d5d5a3d5766 Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Sun, 23 Feb 2020 00:45:30 +0900 Subject: [PATCH] refactor: autosummary: Define AutosummaryEntry as a return type of find_autosummary_*() --- sphinx/ext/autosummary/generate.py | 29 +++++++++++++++++------------ tests/test_ext_autosummary.py | 4 ++-- 2 files changed, 19 insertions(+), 14 deletions(-) diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index f1766ae51c..5a87e4abf0 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -24,7 +24,7 @@ import pydoc import re import sys import warnings -from typing import Any, Callable, Dict, List, Set, Tuple +from typing import Any, Callable, Dict, List, NamedTuple, Set, Tuple from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound from jinja2.sandbox import SandboxedEnvironment @@ -66,6 +66,11 @@ class DummyApplication: pass +AutosummaryEntry = NamedTuple('AutosummaryEntry', [('name', str), + ('path', str), + ('template', str)]) + + def setup_documenters(app: Any) -> None: from sphinx.ext.autodoc import ( ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter, @@ -262,22 +267,22 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, new_files = [] # write - for name, path, template_name in sorted(set(items), key=str): - if path is None: + for entry in sorted(set(items), key=str): + if entry.path is None: # The corresponding autosummary:: directive did not have # a :toctree: option continue - path = output_dir or os.path.abspath(path) + path = output_dir or os.path.abspath(entry.path) ensuredir(path) try: - name, obj, parent, mod_name = import_by_name(name) + name, obj, parent, mod_name = import_by_name(entry.name) except ImportError as e: _warn(__('[autosummary] failed to import %r: %s') % (name, e)) continue - content = generate_autosummary_content(name, obj, parent, template, template_name, + content = generate_autosummary_content(name, obj, parent, template, entry.template, imported_members, app) filename = os.path.join(path, name + suffix) @@ -308,12 +313,12 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, # -- Finding documented entries in files --------------------------------------- -def find_autosummary_in_files(filenames: List[str]) -> List[Tuple[str, str, str]]: +def find_autosummary_in_files(filenames: List[str]) -> List[AutosummaryEntry]: """Find out what items are documented in source/*.rst. See `find_autosummary_in_lines`. """ - documented = [] # type: List[Tuple[str, str, str]] + documented = [] # type: List[AutosummaryEntry] for filename in filenames: with open(filename, encoding='utf-8', errors='ignore') as f: lines = f.read().splitlines() @@ -322,7 +327,7 @@ def find_autosummary_in_files(filenames: List[str]) -> List[Tuple[str, str, str] def find_autosummary_in_docstring(name: str, module: Any = None, filename: str = None - ) -> List[Tuple[str, str, str]]: + ) -> List[AutosummaryEntry]: """Find out what items are documented in the given object's docstring. See `find_autosummary_in_lines`. @@ -342,7 +347,7 @@ def find_autosummary_in_docstring(name: str, module: Any = None, filename: str = def find_autosummary_in_lines(lines: List[str], module: Any = None, filename: str = None - ) -> List[Tuple[str, str, str]]: + ) -> List[AutosummaryEntry]: """Find out what items appear in autosummary:: directives in the given lines. @@ -362,7 +367,7 @@ def find_autosummary_in_lines(lines: List[str], module: Any = None, filename: st toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') template_arg_re = re.compile(r'^\s+:template:\s*(.*?)\s*$') - documented = [] # type: List[Tuple[str, str, str]] + documented = [] # type: List[AutosummaryEntry] toctree = None # type: str template = None @@ -396,7 +401,7 @@ def find_autosummary_in_lines(lines: List[str], module: Any = None, filename: st if current_module and \ not name.startswith(current_module + '.'): name = "%s.%s" % (current_module, name) - documented.append((name, toctree, template)) + documented.append(AutosummaryEntry(name, toctree, template)) continue if not line.strip() or line.startswith(base_indent + " "): diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 3e15ef244c..cc6b0fa383 100644 --- a/tests/test_ext_autosummary.py +++ b/tests/test_ext_autosummary.py @@ -19,7 +19,7 @@ from sphinx import addnodes from sphinx.ext.autosummary import ( autosummary_table, autosummary_toc, mangle_signature, import_by_name, extract_summary ) -from sphinx.ext.autosummary.generate import generate_autosummary_docs +from sphinx.ext.autosummary.generate import AutosummaryEntry, generate_autosummary_docs from sphinx.testing.util import assert_node, etree_parse from sphinx.util.docutils import new_document @@ -328,7 +328,7 @@ def test_autosummary_imported_members(app, status, warning): @pytest.mark.sphinx(testroot='ext-autodoc') def test_generate_autosummary_docs_property(app): with patch('sphinx.ext.autosummary.generate.find_autosummary_in_files') as mock: - mock.return_value = [('target.methods.Base.prop', 'prop', None)] + mock.return_value = [AutosummaryEntry('target.methods.Base.prop', 'prop', None)] generate_autosummary_docs([], output_dir=app.srcdir, builder=app.builder, app=app) content = (app.srcdir / 'target.methods.Base.prop.rst').read_text()