def add_directive_header(self, sig: str) -> None:
sourcename = self.get_sourcename()
if self.doc_as_attr:
self.directivetype = "attribute"
Documenter.add_directive_header(self, sig)
if self.analyzer and '.'.join(self.objpath) in self.analyzer.finals:
self.add_line(" :final:", sourcename)
# add inheritance info, if wanted
if not self.doc_as_attr and self.options.show_inheritance:
sourcename = self.get_sourcename()
self.add_line('', sourcename)
if hasattr(self.object, "__bases__") and len(
self.object.__bases__):
bases = []
for b in self.object.__bases__:
if b is TemporaryDirectory:
bases.append(":py:obj:`~tempfile.TemporaryDirectory`")
elif b.__module__ in ("__builtin__", "builtins"):
bases.append(f':class:`{b.__name__}`')
else:
bases.append(format_annotation(b))
self.add_line(" " + _("Bases: %s") % ", ".join(bases),
sourcename)
def my_add_directive_header(self, sig):
if self.doc_as_attr:
self.directivetype = 'attribute'
Documenter.add_directive_header(self, sig)
if not self.doc_as_attr and self.options.show_inheritance:
sourcename = self.get_sourcename()
self.add_line(u'', sourcename)
if hasattr(self.object, '__bases__') and len(self.object.__bases__):
bases = [b.__module__ in ('__builtin__', 'builtins') and
u':class:`%s`' % b.__name__ or
u':class:`~%s.%s`' % (b.__module__, b.__name__)
for b in self.object.__bases__]
self.add_line(u' ' + _(u'Bases: %s') % ', '.join(bases),
sourcename)
def add_content(self, more_content: Any, no_docstring: bool = True): """ Add extra content (from docstrings, attribute docs etc.), but not the NamedTuple's docstring. :param more_content: :param no_docstring: """ Documenter.add_content(self, more_content, True) # set sourcename and add content from attribute documentation sourcename = self.get_sourcename() params, pre_output, post_output = self._get_docstring() for line in pre_output: self.add_line(line, sourcename)
def add_directive_header(self, sig: str) -> None:
"""
Add the directive header.
:param sig:
"""
sourcename = self.get_sourcename()
if self.doc_as_attr:
self.directivetype = "attribute"
Documenter.add_directive_header(self, sig)
if self.analyzer and '.'.join(self.objpath) in self.analyzer.finals:
self.add_line(" :final:", sourcename)
# add inheritance info, if wanted
if not self.doc_as_attr and self.options.show_inheritance:
_add_generic_bases(self)
def add_directive_header(self, sig):
if self.doc_as_attr:
self.directivetype = 'attribute'
Documenter.add_directive_header(self, sig)
def fix(mod):
if mod == 'kivy._event':
mod = 'kivy.event'
return mod
# add inheritance info, if wanted
if not self.doc_as_attr and self.options.show_inheritance:
self.add_line(u'', '<autodoc>')
if len(self.object.__bases__):
bases = [b.__module__ == '__builtin__' and
u':class:`%s`' % b.__name__ or
u':class:`%s.%s`' % (fix(b.__module__), b.__name__)
for b in self.object.__bases__]
self.add_line(_(u' Bases: %s') % ', '.join(bases),
'<autodoc>')
def import_object(self, raiseerror: bool = False) -> Any:
"""
Import the object given by ``self.modname`` and ``self.objpath`` and set it as ``self.object``.
:param raiseerror:
:returns: :py:obj:`True` if successful, :py:obj:`False` if an error occurred.
"""
self._datadescriptor = False
return Documenter.import_object(self, raiseerror=raiseerror)
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 add_content(self, more_content: Any, no_docstring: bool = True):
r"""
Add extra content (from docstrings, attribute docs etc.),
but not the :class:`typing.NamedTuple`\'s docstring.
:param more_content:
:param no_docstring:
""" # noqa: D400
with warnings.catch_warnings():
# TODO: work out what to do about this
warnings.simplefilter("ignore", RemovedInSphinx50Warning)
Documenter.add_content(self, more_content, True)
# set sourcename and add content from attribute documentation
sourcename = self.get_sourcename()
params, pre_output, post_output = self._get_docstring()
for line in pre_output:
self.add_line(line, sourcename)
def add_directive_header(self, sig):
if self.doc_as_attr:
self.directivetype = 'attribute'
Documenter.add_directive_header(self, sig)
# add inheritance info, if wanted
if not self.doc_as_attr and self.options.show_inheritance:
self.add_line(u'', '<autodoc>')
if (hasattr(self.object, '__bases__')
and len(self.object.__bases__)):
bases = []
for b in self.object.__bases__:
if b.__module__ == '__builtin__':
bases.append(u':class:`%s`' % b.__name__)
elif b.__module__.startswith('gwpy.'):
bases.append(
u':class:`%s.%s`' %
(b.__module__.rsplit('.', 1)[0], b.__name__))
else:
bases.append(u':class:`%s.%s`' %
(b.__module__, b.__name__))
self.add_line(u' Bases: %s' % ', '.join(bases), '<autodoc>')
def add_directive_header(self, sig):
if self.doc_as_attr:
self.directivetype = 'attribute'
Documenter.add_directive_header(self, sig)
# add inheritance info, if wanted
if not self.doc_as_attr and self.options.show_inheritance:
self.add_line(u'', '<autodoc>')
if (hasattr(self.object, '__bases__') and
len(self.object.__bases__)):
bases = []
for b in self.object.__bases__:
if b.__module__ == '__builtin__':
bases.append(u':class:`%s`' % b.__name__)
elif b.__module__.startswith('gwpy.'):
bases.append(u':class:`%s.%s`'
% (b.__module__.rsplit('.', 1)[0],
b.__name__))
else:
bases.append(u':class:`%s.%s`'
% (b.__module__, b.__name__))
self.add_line(u' Bases: %s' % ', '.join(bases),
'<autodoc>')
def add_directive_header(self, sig: str) -> None:
"""
Add the directive header.
:param sig:
"""
sourcename = self.get_sourcename()
if self.doc_as_attr:
self.directivetype = "attribute"
Documenter.add_directive_header(self, sig)
if self.analyzer and '.'.join(self.objpath) in self.analyzer.finals:
self.add_line(" :final:", sourcename)
# add inheritance info, if wanted
if not self.doc_as_attr and self.options.show_inheritance:
self.add_line('', sourcename)
bases = []
if (hasattr(self.object, "__orig_bases__")
and len(self.object.__orig_bases__)
and get_origin(self.object.__orig_bases__[0]) is
self.object.__bases__[0]):
# Last condition guards against classes that don't directly subclass a Generic.
bases = [
format_annotation(b) for b in self.object.__orig_bases__
]
elif hasattr(self.object, "__bases__") and len(
self.object.__bases__):
bases = [format_annotation(b) for b in self.object.__bases__]
if bases:
self.add_line(" " + _("Bases: %s") % ", ".join(bases),
sourcename)
def add_content(self,
more_content: Any,
no_docstring: bool = False) -> None: # type: ignore
"""
Add extra content (from docstrings, attribute docs etc.), but not the class docstring.
:param more_content:
:param no_docstring:
"""
with warnings.catch_warnings():
# TODO: work out what to do about this
warnings.simplefilter("ignore", RemovedInSphinx50Warning)
Documenter.add_content(self, more_content, True)
# set sourcename and add content from attribute documentation
sourcename = self.get_sourcename()
params, pre_output, post_output = self._get_docstring()
self.add_line('', sourcename)
for line in list(self.process_doc([pre_output])):
self.add_line(line, sourcename)
self.add_line('', sourcename)
def _find_signature(self, encoding=None):
docstrings = Documenter.get_doc(self, encoding, 2)
if len(docstrings) != 1:
return
doclines = docstrings[0]
setattr(self, '__new_doclines', doclines)
if not doclines:
return
# match first line of docstring against signature RE
match = yaml_sig_re.match(doclines[0])
if not match:
return
name = match.group(1)
# ok, now jump over remaining empty lines and set the remaining
# lines as the new doclines
i = 1
while i < len(doclines) and not doclines[i].strip():
i += 1
setattr(self, '__new_doclines', doclines[i:])
return name
def _find_signature(self, encoding=None):
docstrings = Documenter.get_doc(self, encoding, 2)
if len(docstrings) != 1:
return
doclines = docstrings[0]
setattr(self, '__new_doclines', doclines)
if not doclines:
return
# match first line of docstring against signature RE
match = yaml_sig_re.match(doclines[0])
if not match:
return
name = match.group(1)
# ok, now jump over remaining empty lines and set the remaining
# lines as the new doclines
i = 1
while i < len(doclines) and not doclines[i].strip():
i += 1
setattr(self, '__new_doclines', doclines[i:])
return name
def get_doc(self, encoding=None, ignore=1):
lines = getattr(self, '__new_doclines', None)
if lines is not None:
return [lines]
return Documenter.get_doc(self, encoding, ignore)
def get_doc(self, encoding=None, ignore=1):
lines = getattr(self, '__new_doclines', None)
if lines is not None:
return [lines]
return Documenter.get_doc(self, encoding, ignore)
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
def document_members(self, all_members):
Documenter.document_members(self, all_members)
def format_signature(self):
if self.args is None and self.env.config.autodoc_docstring_signature:
self.args, self.retann = _format_signature(self.object)
return Documenter.format_signature(self)
