def _add_generic_bases(documenter: Documenter) -> None: """ Add the generic bases to the output of the given Documenter. .. versionadded:: 2.13.0 (undocumented) :param documenter: """ sourcename = documenter.get_sourcename() # add inheritance info, if wanted fully_qualified = getattr(documenter.env.config, "generic_bases_fully_qualified", False) documenter.add_line('', sourcename) bases = [] if (hasattr(documenter.object, "__orig_bases__") and len(documenter.object.__orig_bases__) and get_origin(documenter.object.__orig_bases__[0]) is documenter.object.__bases__[0]): # Last condition guards against classes that don't directly subclass a Generic. bases = [ format_annotation(b, fully_qualified) for b in documenter.object.__orig_bases__ ] elif hasattr(documenter.object, "__bases__") and len( documenter.object.__bases__): bases = [ format_annotation(b, fully_qualified) for b in documenter.object.__bases__ ] if bases: bases_string = ", ".join(bases).replace("typing_extensions.", "typing.") documenter.add_line(" " + _("Bases: %s") % bases_string, sourcename)
def begin_generate( documenter: Documenter, real_modname: Optional[str] = None, check_module: bool = False, ) -> Optional[str]: """ Boilerplate for the top of ``generate`` in :class:`sphinx.ext.autodoc.Documenter` subclasses. .. versionadded:: 0.2.0 :param documenter: :param real_modname: :param check_module: :return: The ``sourcename``, or :py:obj:`None` if certain conditions are met, to indicate that the Documenter class should exit early. """ # Do not pass real_modname and use the name from the __module__ # attribute of the class. # If a class gets imported into the module real_modname # the analyzer won't find the source of the class, if # it looks in real_modname. if not documenter.parse_name(): # need a module to import unknown_module_warning(documenter) return None # now, import the module and get object to document if not documenter.import_object(): return None # If there is no real module defined, figure out which to use. # The real module is used in the module analyzer to look up the module # where the attribute documentation would actually be found in. # This is used for situations where you have a module that collects the # functions and classes of internal submodules. guess_modname = documenter.get_real_modname() documenter.real_modname = real_modname or guess_modname # try to also get a source code analyzer for attribute docs try: documenter.analyzer = ModuleAnalyzer.for_module( documenter.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 # type: ignore # at least add the module.__file__ as a dependency if hasattr(documenter.module, "__file__") and documenter.module.__file__: documenter.directive.filename_set.add(documenter.module.__file__) else: documenter.directive.filename_set.add(documenter.analyzer.srcname) if documenter.real_modname != guess_modname: # Add module to dependency list if target object is defined in other module. try: analyzer = ModuleAnalyzer.for_module(guess_modname) documenter.directive.filename_set.add(analyzer.srcname) except PycodeError: pass # check __module__ of object (for members not given explicitly) if check_module: if not documenter.check_module(): return None sourcename = documenter.get_sourcename() # make sure that the result starts with an empty line. This is # necessary for some situations where another directive preprocesses # reST and no starting newline is present documenter.add_line('', sourcename) return sourcename