IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

refactor: autosummary: Define AutosummaryEntry as a return type of find_autosummary_*()

Browse Source
This commit is contained in:
Takeshi KOMIYA 2020-02-23 00:45:30 +09:00
parent 11d9a97a34
commit 55083d5e03
1 changed files with 17 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
sphinx/ext/autosummary/generate.py
View File

@ -25,7 +25,7 @@ import pydoc
import re import re
import sys import sys
import warnings import warnings
from typing import Any, Callable, Dict, List, Set, Tuple, Type from typing import Any, Callable, Dict, List, NamedTuple, Set, Tuple, Type
from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound
from jinja2.sandbox import SandboxedEnvironment from jinja2.sandbox import SandboxedEnvironment
@ -58,6 +58,11 @@ class DummyApplication:
self.verbosity = 0 self.verbosity = 0
AutosummaryEntry = NamedTuple('AutosummaryEntry', [('name', str),
('path', str),
('template', str)])
def setup_documenters(app: Any) -> None: def setup_documenters(app: Any) -> None:
from sphinx.ext.autodoc import ( from sphinx.ext.autodoc import (
ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter, ModuleDocumenter, ClassDocumenter, ExceptionDocumenter, DataDocumenter,
@ -246,22 +251,22 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
new_files = [] new_files = []
# write # write
for name, path, template_name in sorted(set(items), key=str): for entry in sorted(set(items), key=str):
if path is None: if entry.path is None:
# The corresponding autosummary:: directive did not have # The corresponding autosummary:: directive did not have
# a :toctree: option # a :toctree: option
continue continue
path = output_dir or os.path.abspath(path) path = output_dir or os.path.abspath(entry.path)
ensuredir(path) ensuredir(path)
try: try:
name, obj, parent, mod_name = import_by_name(name) name, obj, parent, mod_name = import_by_name(entry.name)
except ImportError as e: except ImportError as e:
_warn('[autosummary] failed to import %r: %s' % (name, e)) _warn('[autosummary] failed to import %r: %s' % (name, e))
continue continue
content = generate_autosummary_content(name, obj, parent, template, template_name, content = generate_autosummary_content(name, obj, parent, template, entry.template,
imported_members, app, recursive) imported_members, app, recursive)
filename = os.path.join(path, name + suffix) filename = os.path.join(path, name + suffix)
@ -291,12 +296,12 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
# -- Finding documented entries in files --------------------------------------- # -- 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. """Find out what items are documented in source/*.rst.
See `find_autosummary_in_lines`. See `find_autosummary_in_lines`.
""" """
documented = [] # type: List[Tuple[str, str, str]] documented = [] # type: List[AutosummaryEntry]
for filename in filenames: for filename in filenames:
with open(filename, encoding='utf-8', errors='ignore') as f: with open(filename, encoding='utf-8', errors='ignore') as f:
lines = f.read().splitlines() lines = f.read().splitlines()
@ -305,7 +310,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 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. """Find out what items are documented in the given object's docstring.
See `find_autosummary_in_lines`. See `find_autosummary_in_lines`.
@ -325,7 +330,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 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 """Find out what items appear in autosummary:: directives in the
given lines. given lines.
@ -345,7 +350,7 @@ def find_autosummary_in_lines(lines: List[str], module: Any = None, filename: st
toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$')
template_arg_re = re.compile(r'^\s+:template:\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 toctree = None # type: str
template = None template = None
@ -379,7 +384,7 @@ def find_autosummary_in_lines(lines: List[str], module: Any = None, filename: st
if current_module and \ if current_module and \
not name.startswith(current_module + '.'): not name.startswith(current_module + '.'):
name = "%s.%s" % (current_module, name) name = "%s.%s" % (current_module, name)
documented.append((name, toctree, template)) documented.append(AutosummaryEntry(name, toctree, template))
continue continue
if not line.strip() or line.startswith(base_indent + " "): if not line.strip() or line.startswith(base_indent + " "):