def process_generate_options(app: Sphinx) -> None:
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))]
else:
ext = list(app.config.source_suffix)
genfiles = [genfile + (not genfile.endswith(tuple(ext)) and ext[0] or '')
for genfile in genfiles]
for entry in genfiles[:]:
if not path.isfile(path.join(app.srcdir, entry)):
logger.warning(__('autosummary_generate: file not found: %s'), entry)
genfiles.remove(entry)
if not genfiles:
return
suffix = get_rst_suffix(app)
if suffix is None:
logger.warning(__('autosummary generats .rst files internally. '
'But your source_suffix does not contain .rst. Skipped.'))
return
from sphinx.ext.autosummary.generate import generate_autosummary_docs
imported_members = app.config.autosummary_imported_members
with mock(app.config.autosummary_mock_imports):
generate_autosummary_docs(genfiles, builder=app.builder,
suffix=suffix, base_path=app.srcdir,
app=app, imported_members=imported_members)
def import_object(self, raiseerror: bool = False) -> bool:
"""Overrides the default object importing method"""
success = False
with mock(self.config.autodoc_mock_imports):
try:
ret = importer.import_object(
self.modname,
self.objpath,
self.objtype,
attrgetter=self.get_attr,
warningiserror=self.config.autodoc_warningiserror,
)
self.module, self.parent, self.object_name, self.object = ret
if ismock(self.object):
self.object = undecorate(self.object)
success = True
except ImportError as exc:
if raiseerror:
raise
logger.warning(exc.args[0],
type="autodoc",
subtype="import_object")
self.env.note_reread()
success = False
return success
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 = list(app.config.source_suffix)
genfiles = [genfile + (not genfile.endswith(tuple(ext)) and ext[0] or '')
for genfile in genfiles]
suffix = get_rst_suffix(app)
if suffix is None:
logger.warning(__('autosummary generats .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):
generate_autosummary_docs(genfiles, builder=app.builder,
warn=logger.warning, info=logger.info,
suffix=suffix, base_path=app.srcdir,
app=app, imported_members=imported_members)
def get_template_field(env, fullname):
"""
Gets template fields for specific operator class.
:param env: env config
:param fullname: Full path to operator class.
For example: ``airflow.providers.google.cloud.operators.vision.CloudVisionCreateProductSetOperator``
:return: List of template field
:rtype: list[str]
"""
modname, classname = fullname.rsplit(".", 1)
try:
with mock(env.config.autodoc_mock_imports):
mod = import_module(modname)
except ImportError:
raise RoleException(f"Error loading {modname} module.")
clazz = getattr(mod, classname)
if not clazz:
raise RoleException(
f"Error finding {classname} class in {modname} module.")
template_fields = getattr(clazz, "template_fields")
if not template_fields:
raise RoleException(
f"Could not find the template fields for {classname} class in {modname} module."
)
return list(template_fields)
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 import_by_name(self, name: str, prefixes: List[str]) -> Tuple[str, Any, Any, str]:
with mock(self.config.autosummary_mock_imports):
try:
return import_by_name(name, prefixes)
except ImportError as exc:
# check existence of instance attribute
try:
return import_ivar_by_name(name, prefixes)
except ImportError:
pass
raise exc # re-raise ImportError if instance attribute not found
def test_ismock():
with mock(['sphinx.unknown']):
mod1 = import_module('sphinx.unknown')
mod2 = import_module('sphinx.application')
class Inherited(mod1.Class):
pass
assert ismock(mod1) is True
assert ismock(mod1.Class) is True
assert ismock(Inherited) is False
assert ismock(mod2) is False
assert ismock(mod2.Sphinx) is False
def import_by_name(self, name: str, prefixes: List[str]) -> Tuple[str, Any, Any, str]:
with mock(self.config.autosummary_mock_imports):
try:
return import_by_name(name, prefixes)
except ImportExceptionGroup as exc:
# check existence of instance attribute
try:
return import_ivar_by_name(name, prefixes)
except ImportError as exc2:
if exc2.__cause__:
errors: List[BaseException] = exc.exceptions + [exc2.__cause__]
else:
errors = exc.exceptions + [exc2]
raise ImportExceptionGroup(exc.args[0], errors)
def test_mock():
modname = 'sphinx.unknown'
submodule = modname + '.submodule'
assert modname not in sys.modules
with pytest.raises(ImportError):
import_module(modname)
with mock([modname]):
import_module(modname)
assert modname in sys.modules
assert isinstance(sys.modules[modname], _MockModule)
# submodules are also mocked
import_module(submodule)
assert submodule in sys.modules
assert isinstance(sys.modules[submodule], _MockModule)
assert modname not in sys.modules
with pytest.raises(ImportError):
import_module(modname)
def test_mock_does_not_follow_upper_modules():
with mock(['sphinx.unknown.module']):
with pytest.raises(ImportError):
import_module('sphinx.unknown')
if not git_sha:
try:
git_sha = subprocess.check_output(["git", "log", "--pretty=format:'%h'", "-n1"]).decode('ascii').replace("'","").strip()
except:
git_sha = u'0000000'
git_sha = git_sha[:7] if len(git_sha) > 7 else git_sha
version = str(version_long + u"-" + git_sha)
# The full version, including alpha/beta/rc tags
release = str(version_long)
# generate table of supported operators and their devices
# mock torch required by supported_op_devices
with mock(["torch"]):
sys.path.insert(0, os.path.abspath('./'))
import supported_op_devices
supported_op_devices.main(["op_inclusion"])
# Uncomment to keep warnings in the output. Useful for verbose build and output debugging.
# keep_warnings = True
# hack: version is used for html creation, so put the version picker
# link here as well:
option_on = " selected"
option_off = ""
if "dev" in version_long:
release_opt = option_off
master_opt = option_on
option_nr = 1
def get_items(self, names: List[str]) -> List[Tuple[str, str, str, str]]:
"""Try to import the given names, and return a list of
``[(name, signature, summary_string, real_name), ...]``.
"""
prefixes = get_import_prefixes_from_env(self.env)
items = [] # type: List[Tuple[str, str, str, str]]
max_item_chars = 50
for name in names:
display_name = name
if name.startswith('~'):
name = name[1:]
display_name = name.split('.')[-1]
try:
with mock(self.config.autosummary_mock_imports):
real_name, obj, parent, modname = import_by_name(
name, prefixes=prefixes)
except ImportError:
logger.warning(__('autosummary: failed to import %s'),
name,
location=self.get_source_info())
continue
self.bridge.result = StringList() # initialize for each documenter
full_name = real_name
if not isinstance(obj, ModuleType):
# give explicitly separated module name, so that members
# of inner classes can be documented
full_name = modname + '::' + full_name[len(modname) + 1:]
# NB. using full_name here is important, since Documenters
# handle module prefixes slightly differently
doccls = get_documenter(self.env.app, obj, parent)
documenter = doccls(self.bridge, full_name)
if not documenter.parse_name():
logger.warning(__('failed to parse name %s'),
real_name,
location=self.get_source_info())
items.append((display_name, '', '', real_name))
continue
if not documenter.import_object():
logger.warning(__('failed to import object %s'),
real_name,
location=self.get_source_info())
items.append((display_name, '', '', real_name))
continue
if documenter.options.members and not documenter.check_module():
continue
# try to also get a source code analyzer for attribute docs
try:
documenter.analyzer = ModuleAnalyzer.for_module(
documenter.get_real_modname())
# parse right now, to get PycodeErrors on parsing (results will
# be cached anyway)
documenter.analyzer.find_attr_docs()
except PycodeError as err:
logger.debug('[autodoc] module analyzer failed: %s', err)
# no source file -- e.g. for builtin and C modules
documenter.analyzer = None
# -- Grab the signature
try:
sig = documenter.format_signature(show_annotation=False)
except TypeError:
# the documenter does not support ``show_annotation`` option
sig = documenter.format_signature()
if not sig:
sig = ''
else:
max_chars = max(10, max_item_chars - len(display_name))
sig = mangle_signature(sig, max_chars=max_chars)
# -- Grab the summary
documenter.add_content(None)
summary = extract_summary(self.bridge.result.data[:],
self.state.document)
items.append((display_name, sig, summary, real_name))
return items
try:
git_sha = subprocess.check_output(
["git", "log", "--pretty=format:'%h'",
"-n1"]).decode('ascii').replace("'", "").strip()
except:
git_sha = u'0000000'
git_sha = git_sha[:7] if len(git_sha) > 7 else git_sha
version = str(version_long + u"-" + git_sha)
# The full version, including alpha/beta/rc tags
release = str(version_long)
# generate table of supported operators and their devices
# mock torch required by supported_op_devices
with mock(["torch", "numba"]):
sys.path.insert(0, os.path.abspath('./'))
import operations_table
operations_table.operations_table("fn_table")
operations_table.fn_to_op_table("fn_to_op_table")
import autodoc_submodules
autodoc_submodules.op_autodoc("op_autodoc")
autodoc_submodules.fn_autodoc("fn_autodoc")
# Uncomment to keep warnings in the output. Useful for verbose build and output debugging.
# keep_warnings = True
# hack: version is used for html creation, so put the version picker
# link here as well:
option_on = " selected"
