def generate_autosummary_docs(sources: List[str],
output_dir: str = None,
suffix: str = '.rst',
base_path: str = None,
builder: Builder = None,
template_dir: str = None,
imported_members: bool = False,
app: Any = None,
overwrite: bool = True,
encoding: str = 'utf-8') -> None:
if builder:
warnings.warn(
'builder argument for generate_autosummary_docs() is deprecated.',
RemovedInSphinx50Warning,
stacklevel=2)
if template_dir:
warnings.warn(
'template_dir argument for generate_autosummary_docs() is deprecated.',
RemovedInSphinx50Warning,
stacklevel=2)
showed_sources = list(sorted(sources))
if len(showed_sources) > 20:
showed_sources = showed_sources[:10] + ['...'] + showed_sources[-10:]
logger.info(
__('[autosummary] generating autosummary for: %s') %
', '.join(showed_sources))
if output_dir:
logger.info(__('[autosummary] writing to %s') % output_dir)
if base_path is not None:
sources = [os.path.join(base_path, filename) for filename in sources]
template = AutosummaryRenderer(app)
# read
items = find_autosummary_in_files(sources)
# keep track of new files
new_files = []
if app:
filename_map = app.config.autosummary_filename_map
else:
filename_map = {}
# write
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(entry.path)
ensuredir(path)
try:
name, obj, parent, modname = import_by_name(entry.name)
qualname = name.replace(modname + ".", "")
except ImportExceptionGroup as exc:
try:
# try to import as an instance attribute
name, obj, parent, modname = import_ivar_by_name(entry.name)
qualname = name.replace(modname + ".", "")
except ImportError as exc2:
if exc2.__cause__:
exceptions: List[BaseException] = exc.exceptions + [
exc2.__cause__
]
else:
exceptions = exc.exceptions + [exc2]
errors = list(
set("* %s: %s" % (type(e).__name__, e)
for e in exceptions))
logger.warning(
__('[autosummary] failed to import %s.\nPossible hints:\n%s'
), entry.name, '\n'.join(errors))
continue
context: Dict[str, Any] = {}
if app:
context.update(app.config.autosummary_context)
content = generate_autosummary_content(name, obj, parent, template,
entry.template,
imported_members, app,
entry.recursive, context,
modname, qualname)
filename = os.path.join(path, filename_map.get(name, name) + suffix)
if os.path.isfile(filename):
with open(filename, encoding=encoding) as f:
old_content = f.read()
if content == old_content:
continue
elif overwrite: # content has changed
with open(filename, 'w', encoding=encoding) as f:
f.write(content)
new_files.append(filename)
else:
with open(filename, 'w', encoding=encoding) as f:
f.write(content)
new_files.append(filename)
# descend recursively to new files
if new_files:
generate_autosummary_docs(new_files,
output_dir=output_dir,
suffix=suffix,
base_path=base_path,
builder=builder,
template_dir=template_dir,
imported_members=imported_members,
app=app,
overwrite=overwrite)
def generate_docs(
self,
source_filenames: List[str],
output_dir: str = None,
suffix: str = ".rst",
base_path: str = None,
imported_members: bool = False,
overwrite: bool = True,
encoding: str = "utf-8",
) -> None:
"""
Generate and write stub files for objects defined in the :rst:dir:`automodapi`
and :rst:dir:`automodsumm` directives.
Parameters
----------
source_filenames : List[str]
A list of all filenames for with the :rst:dir:`automodapi` and
:rst:dir:`automodsumm` directives will be searched for.
output_dir : `str`
Directory for which the stub files will be written to.
suffix : `str`
(Default ``".rst"``) Suffix given to the written stub files.
base_path : `str`
The common base path for the filenames listed in ``source_filenames``.
This is typically the source directory of the Sphinx application.
imported_members : `bool`
(Default `False`) Set `True` to include imported members in the
stub file documentation for *module* object types.
overwrite : `bool`
(Default `True`) Will cause existing stub files to be overwritten.
encoding : `str`
(Default: ``"utf-8"``) Encoding for the written stub files.
.. note:: Adapted from
:func:`sphinx.ext.autosummary.generate.generate_autosummary_docs`.
"""
app = self.app
_info = self.logger.info
_warn = self.logger.warning
showed_sources = list(sorted(source_filenames))
_info(
__(f"[automodsumm] generating stub files for {len(showed_sources)} sources"
))
if output_dir:
_info(__(f"[automodsumm] writing to {output_dir}"))
if base_path is not None:
source_filenames = [
os.path.join(base_path, filename)
for filename in source_filenames
]
template = AutomodsummRenderer(app)
# read
items = self.find_in_files(source_filenames)
# keep track of new files
new_files = []
if app:
filename_map = app.config.autosummary_filename_map
else:
filename_map = {}
# write
for entry in sorted(set(items), key=str):
if entry.path is None:
# The corresponding automodsumm:: directive did not have
# a :toctree: option
continue
path = output_dir or os.path.abspath(entry.path)
ensuredir(path)
try:
name, obj, parent, modname = import_by_name(entry.name)
qualname = name.replace(modname + ".", "")
except ImportError as e:
try:
# try to import as an instance attribute
name, obj, parent, modname = import_ivar_by_name(
entry.name)
qualname = name.replace(modname + ".", "")
except ImportError:
_warn(
__(f"[automodsumm] failed to import {entry.name}: {e}")
)
continue
context = {}
if app:
context.update(app.config.autosummary_context)
content = generate_autosummary_content(
name,
obj,
parent,
template,
entry.template,
imported_members,
app,
entry.recursive,
context,
modname,
qualname,
)
filename = os.path.join(path,
filename_map.get(name, name) + suffix)
if os.path.isfile(filename):
with open(filename, encoding=encoding) as f:
old_content = f.read()
if content == old_content:
continue
elif overwrite: # content has changed
with open(filename, "w", encoding=encoding) as f:
f.write(content)
new_files.append(filename)
else:
with open(filename, "w", encoding=encoding) as f:
f.write(content)
new_files.append(filename)
# descend recursively to new files
if new_files:
self.generate_docs(
new_files,
output_dir=output_dir,
suffix=suffix,
base_path=base_path,
imported_members=imported_members,
overwrite=overwrite,
)