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 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)
def get_template_field(env, fullname): """ Gets template fields for specific operator class. :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 get_template_field(env, fullname): """ Gets template fields for specific operator class. :param fullname: Full path to operator class. For example: ``airflow.contrib.operators.gcp_vision_operator.CloudVisionProductSetCreateOperator`` :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("Error loading %s module." % (modname, )) clazz = getattr(mod, classname) if not clazz: raise RoleException("Error finding %s class in %s module." % (classname, modname)) template_fields = getattr(clazz, "template_fields") if not template_fields: raise RoleException( "Could not find the template fields for %s class in %s module." % (classname, modname) ) return list(template_fields)
def get_template_field(env, fullname): """ Gets template fields for specific operator class. :param fullname: Full path to operator class. For example: ``airflow.contrib.operators.gcp_vision_operator.CloudVisionProductSetCreateOperator`` :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("Error loading %s module." % (modname, )) clazz = getattr(mod, classname) if not clazz: raise RoleException("Error finding %s class in %s module." % (classname, modname)) template_fields = getattr(clazz, "template_fields") if not template_fields: raise RoleException( "Could not find the template fields for %s class in %s module." % (classname, modname)) return list(template_fields)
def test_mock(): modname = 'sphinx.unknown' submodule = modname + '.submodule' assert modname not in sys.modules with pytest.raises(ImportError): __import__(modname) with mock([modname]): __import__(modname) assert modname in sys.modules assert isinstance(sys.modules[modname], _MockModule) # submodules are also mocked __import__(submodule) assert submodule in sys.modules assert isinstance(sys.modules[submodule], _MockModule) assert modname not in sys.modules with pytest.raises(ImportError): __import__(modname)
def test_mock_does_not_follow_upper_modules(): with mock(['sphinx.unknown.module']): with pytest.raises(ImportError): __import__('sphinx.unknown')
def get_items(self, names): # type: (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(__('failed to import %s'), name) items.append((name, '', '', name)) 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) items.append((display_name, '', '', real_name)) continue if not documenter.import_object(): logger.warning(__('failed to import object %s'), real_name) 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 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