def _generate_stubs(app: Sphinx):
gen_files = app.config.autosummary_generate
if gen_files and not hasattr(gen_files, "__len__"):
env = app.builder.env
gen_files = [
env.doc2path(x, base=None) for x in env.found_docs
if Path(env.doc2path(x)).is_file()
]
if not gen_files:
return
ext = app.config.source_suffix
gen_files = [
genfile + ("" if genfile.endswith(tuple(ext)) else ext[0])
for genfile in gen_files
]
suffix = autosummary.get_rst_suffix(app)
if suffix is None:
return
generate_autosummary_docs(
gen_files,
builder=app.builder,
warn=logger.warning,
info=logger.info,
suffix=suffix,
base_path=app.srcdir,
imported_members=True,
app=app,
)
def process_generate_options(app):
genfiles = app.config.autosummary_generate
if genfiles and not hasattr(genfiles, '__len__'):
env = app.builder.env
genfiles = [env.doc2path(x, base=None) for x in env.found_docs
if osp.isfile(env.doc2path(x))]
if not genfiles:
return
ext = tuple(app.config.source_suffix)
genfiles = [genfile + (not genfile.endswith(ext) and ext[0] or '')
for genfile in genfiles]
try:
from sphinx.ext.autosummary import get_rst_suffix
suffix = get_rst_suffix(app)
except ImportError:
suffix = '.rst'
if suffix is None:
logger.warning('autosummary generats .rst files internally. '
'But your source_suffix does not contain .rst. Skipped.')
return
generate_autosummary_docs(genfiles, builder=app.builder,
warn=logger.warning, info=logger.info,
suffix=suffix, base_path=app.srcdir, app=app)
def process_generate_options(app):
# type: (Sphinx) -> None
genfiles = app.config.autosummary_generate
if genfiles and not hasattr(genfiles, '__len__'):
env = app.builder.env
genfiles = [
env.doc2path(x, base=None) for x in env.found_docs
if os.path.isfile(env.doc2path(x))
]
if not genfiles:
return
from sphinx.ext.autosummary.generate import generate_autosummary_docs
ext = app.config.source_suffix
genfiles = [
genfile + (not genfile.endswith(tuple(ext)) and ext[0] or '')
for genfile in genfiles
]
suffix = autosummary.get_rst_suffix(app)
if suffix is None:
return
generate_autosummary_docs(genfiles,
builder=app.builder,
warn=logger.warning,
info=logger.info,
suffix=suffix,
base_path=app.srcdir,
imported_members=True)
def process_generate_options(app):
genfiles = app.config.autosummary_generate
if genfiles and not hasattr(genfiles, '__len__'):
env = app.builder.env
genfiles = [env.doc2path(x, base=None) for x in env.found_docs
if osp.isfile(env.doc2path(x))]
if not genfiles:
return
ext = tuple(app.config.source_suffix)
genfiles = [genfile + (not genfile.endswith(ext) and ext[0] or '')
for genfile in genfiles]
try:
from sphinx.ext.autosummary import get_rst_suffix
suffix = get_rst_suffix(app)
except ImportError:
suffix = '.rst'
if suffix is None:
logger.warning('autosummary generats .rst files internally. '
'But your source_suffix does not contain .rst. Skipped.')
return
generate_autosummary_docs(genfiles, builder=app.builder,
warn=logger.warning, info=logger.info,
suffix=suffix, base_path=app.srcdir, app=app)
def __call__(self, app: "Sphinx"):
"""
Scan through source files, check for the :rst:dir:`automodsumm` and
:rst:dir:`automodapi` directives, and auto generate any associated
stub files.
Parameters
----------
app : `~sphinx.application.Sphinx`
Instance of the Sphinx application.
.. note:: Adapted from :func:`sphinx.ext.autosummary.process_generate_options`.
"""
self.app = app
genfiles = app.config.autosummary_generate
if genfiles is True:
env = app.builder.env
genfiles = [
env.doc2path(x, base=None) for x in env.found_docs
if os.path.isfile(env.doc2path(x))
]
elif genfiles is False:
pass
else:
ext = list(app.config.source_suffix)
genfiles = [
genfile + (ext[0] if not genfile.endswith(tuple(ext)) else "")
for genfile in genfiles
]
for entry in genfiles[:]:
if not os.path.isfile(os.path.join(app.srcdir, entry)):
self.logger.warning(
__(f"automodsumm_generate: file not found: {entry}"))
genfiles.remove(entry)
if not genfiles:
return
suffix = get_rst_suffix(app)
if suffix is None:
self.logger.warning(
__("automodsumm generates .rst files internally. "
"But your source_suffix does not contain .rst. Skipped."))
return
imported_members = app.config.autosummary_imported_members
with mock(app.config.autosummary_mock_imports):
self.generate_docs(
genfiles,
suffix=suffix,
base_path=app.srcdir,
imported_members=imported_members,
overwrite=app.config.autosummary_generate_overwrite,
encoding=app.config.source_encoding,
)
def process_generate_options_custom_files(app):
orig_suffix = get_rst_suffix(app)
new_suffix = app.config.custom_autosummary_new_suffix
generated_dirname = app.config.custom_autosummary_generated_dirname
filename_map = {
name + orig_suffix: name + new_suffix
for name in app.config.custom_autosummary_names_with_new_suffix
}
with patch_os_path_join(generated_dirname, filename_map):
process_generate_options(app)
