def i_add_directive_header(self, sig):
ClassLevelDocumenter.add_directive_header(self, sig)
source_name = self.get_sourcename()
if not self.options.annotation:
if not self._datadescriptor:
# obtain annotation for this attribute
annotations = getattr(self.parent, '__annotations__', {})
if annotations and self.objpath[-1] in annotations:
objrepr = stringify_type_hint(annotations.get(
self.objpath[-1]))
self.add_line(' :type: ' + objrepr, source_name)
else:
key = ('.'.join(self.objpath[:-1]), self.objpath[-1])
if self.analyzer and key in self.analyzer.annotations:
v = self.analyzer.annotations[key]
if v == "_np.ndarray":
v = "ndarray"
elif v == "_typing.Sequence[str]":
v = "list of str"
else:
v = v.replace("_typing.", "")
v = v.replace("_np.", "")
self.add_line(f" :type: {v}", source_name)
# ## Remove (= None).
# try:
# obj_repr = object_description(self.object)
# self.add_line(' :value: ' + obj_repr, source_name)
# except ValueError:
# pass
elif self.options.annotation is SUPPRESS:
pass
else:
self.add_line(' :annotation: %s' % self.options.annotation,
source_name)
def add_directive_header(self, sig):
# We can't call super() here, because we want to *skip* executing
# FunctionDocumenter.add_directive_header, because starting in Sphinx
# 2.1 it does its own sniffing, which is worse than ours and will
# break ours. So we jump straight to the superclass.
ClassLevelDocumenter.add_directive_header(self, sig)
passthrough_option_lines(self, extended_method_option_spec)
def add_directive_header(self, sig):
""" Add the directive header 'attribute' with the annotation
option set to the trait definition.
"""
ClassLevelDocumenter.add_directive_header(self, sig)
try:
definition = trait_definition(
cls=self.parent,
trait_name=self.object_name,
)
except ValueError:
# Without this, a failure to find the trait definition aborts
# the whole documentation build.
logger.warning(
"No definition for the trait {!r} could be found in "
"class {!r}.".format(self.object_name, self.parent),
exc_info=True)
return
# Workaround for enthought/traits#493: if the definition is multiline,
# throw away all lines after the first.
if "\n" in definition:
definition = definition.partition("\n")[0] + " …"
self.add_line(" :annotation: = {0}".format(definition), "<autodoc>")
def add_content(self, more_content, no_docstring=False):
"""Patch to add the documentation from the mock object
before any other documentation."""
encoding = self.analyzer and self.analyzer.encoding
docstrings = self.get_doc(encoding)
for i, line in enumerate(self.process_doc(docstrings)):
self.add_line(line, '<autodoc>', i)
ClassLevelDocumenter.add_content(self, more_content, True)
def add_directive_header(self, sig):
""" Add the directive header 'attribute' with the annotation
option set to the trait definition.
"""
ClassLevelDocumenter.add_directive_header(self, sig)
definition = self._get_trait_definition()
self.add_line(u' :annotation: = {0}'.format(definition), '<autodoc>')
def add_directive_header(self, sig):
""" Add the directive header 'attribute' with the annotation
option set to the trait definition.
"""
ClassLevelDocumenter.add_directive_header(self, sig)
definition = self._get_trait_definition()
self.add_line(' :annotation: = {0}'.format(definition), '<autodoc>')
def import_object(self):
"""Load an object."""
# Get the object
if not ClassLevelDocumenter.import_object(self):
return False
# Reload modules
self.parent = reload_object(self.parent)
reload(import_module(self.modname))
# Get the new object
return ClassLevelDocumenter.import_object(self)
def add_directive_header(self, sig: str):
"""
Add the directive's header.
:param sig:
"""
sourcename = self.get_sourcename()
no_value = self.options.get("no-value", False)
no_type = self.options.get("no-type", False)
if not self.options.get("annotation", ''):
ClassLevelDocumenter.add_directive_header(self, sig)
# data descriptors do not have useful values
if not no_value and not self._datadescriptor:
if "value" in self.options:
self.add_line(" :value: " + self.options["value"],
sourcename)
else:
with suppress(ValueError):
if self.object is not INSTANCEATTR:
objrepr = object_description(self.object)
self.add_line(" :value: " + objrepr, sourcename)
self.add_line('', sourcename)
if not no_type:
if "type" in self.options:
self.add_line(type_template % self.options["type"],
sourcename)
else:
# obtain type annotation for this attribute
the_type = get_variable_type(self)
if not the_type.strip():
obj_type = type(self.object)
if obj_type is object:
return
try:
the_type = format_annotation(obj_type)
except Exception:
return
line = type_template % the_type
self.add_line(line, sourcename)
else:
super().add_directive_header(sig)
def add_content(self, more_content, no_docstring=False):
# Remember the original no_docstring parameter.
_no_docstring = no_docstring
# If this attribute appears to be a Column...
if (isinstance(self.object, Column)
and hasattr(self.object, COLUMN_META_ATTR)):
# ...we really want to document it.
_no_docstring = False
elif not self._datadescriptor:
# if it's not a data descriptor, its docstring is very probably the
# wrong thing to display
_no_docstring = True
ClassLevelDocumenter.add_content(self, more_content, _no_docstring)
def add_directive_header(self, sig):
""" Add the directive header 'attribute' with the annotation
option set to the trait definition.
"""
ClassLevelDocumenter.add_directive_header(self, sig)
definition = self._get_trait_definition()
# Workaround for enthought/traits#493: if the definition is multiline,
# throw away all lines after the first.
if "\n" in definition:
definition = definition.partition("\n")[0] + " …"
self.add_line(" :annotation: = {0}".format(definition), "<autodoc>")
def add_directive_header(self, sig):
""" Add the sphinx directives.
Add the 'attribute' directive with the annotation option
set to the traitlet type
"""
ClassLevelDocumenter.add_directive_header(self, sig)
if hasattr(self, 'get_sourcename'):
sourcename = self.get_sourcename()
else:
sourcename = u'<autodoc>'
trait_type = type(self.object).__name__
self.add_line(' :annotation: = {0}'.format(trait_type), sourcename)
def add_directive_header(self, sig: str) -> None:
ClassLevelDocumenter.add_directive_header(self, sig)
sourcename = self.get_sourcename()
if not self.options.annotation:
if not self._datadescriptor:
try:
objrepr = str(int(self.object))
except ValueError:
pass
else:
self.add_line(' :annotation: = ' + objrepr, sourcename)
elif self.options.annotation is SUPPRESS:
pass
else:
self.add_line(' :annotation: %s' % self.options.annotation,
sourcename)
def import_object(self):
# type: () -> Any
ret = ClassLevelDocumenter.import_object(self)
if not ret:
return ret
# get parent's class
parent_cls = self.parent
if not isinstance(parent_cls, type):
parent_cls = parent_cls.__class__ # if instance, get its class
# to distinguish classmethod/staticmethod
obj = parent_cls.__dict__.get(self.object_name)
if obj is None:
obj = self.object
if isclassmethod(obj):
self.directivetype = 'classmethod'
# document class and static members before ordinary ones
self.member_order = self.member_order - 1
elif isstaticmethod(obj, cls=parent_cls, name=self.object_name):
self.directivetype = 'staticmethod'
# document class and static members before ordinary ones
self.member_order = self.member_order - 1
else:
self.directivetype = 'method'
return ret
def add_directive_header(self, sig):
ClassLevelDocumenter.add_directive_header(self, sig)
if not self.options.annotation:
if not self._datadescriptor:
try:
objrepr = safe_repr(self.object)
except ValueError:
pass
else:
if not SKIP_ANNOTATION_RE.match(self.fullname):
self.add_line(u' :annotation: = ' + objrepr,
'<autodoc>')
elif self.options.annotation is SUPPRESS:
pass
else:
self.add_line(u' :annotation: %s' % self.options.annotation,
'<autodoc>')
def import_object(self):
ret = ClassLevelDocumenter.import_object(self)
if self.object.static:
self.directivetype = 'staticmethod'
self.member_order = self.member_order - 1
else:
self.directivetype = 'method'
return ret
def add_directive_header(self, sig):
""" Add the sphinx directives.
Add the 'attribute' directive with the annotation option
set to the trait definition.
"""
ClassLevelDocumenter.add_directive_header(self, sig)
if hasattr(self, 'get_sourcename'):
sourcename = self.get_sourcename()
else:
sourcename = u'<autodoc>'
try:
definition = get_trait_definition(self.parent, self.object_name)
except DefinitionError as error:
self.directive.warn(error.args[0])
else:
self.add_line(
' :annotation: = {0}'.format(definition), sourcename)
def generate(self, more_content=None, real_modname=None,
check_module=False, all_members=False):
"""Patch to add a header."""
# Get object
if not self.parse_name() or not self.import_object():
return
# Check if header needed
tangotype = type(self.object)
autodevice = getattr(self.env.config, 'autodevice', False)
if autodevice and not self.started[tangotype]:
# Tag as started
self.started[tangotype] = True
self.indent, temp = '', self.indent
# Add header
self.add_line(self.section, '<autodoc>')
self.add_line("-" * len(self.section), '<autodoc>')
self.indent = temp
# Generate documentation
ClassLevelDocumenter.generate(self, more_content, real_modname,
check_module, all_members)
def import_object(self):
# type: () -> Any
ret = ClassLevelDocumenter.import_object(self)
if not ret:
return ret
# Change the object to the fget method. Ignore everything else.
self.object = self.object.fget
# to distinguish classmethod/staticmethod
obj = self.parent.__dict__.get(self.object_name)
if obj is None:
obj = self.object
self.directivetype = 'attribute' # Treat the property like an attribute in terms of formatting. The object is otherwise treated as a method.
return ret
def import_object(self):
# type: () -> Any
ret = ClassLevelDocumenter.import_object(self)
if not ret:
return ret
# Change the object to the fget method. Ignore everything else.
self.object = self.object.fget
# to distinguish classmethod/staticmethod
obj = self.parent.__dict__.get(self.object_name)
if obj is None:
obj = self.object
self.directivetype = 'attribute' # Treat the property like an attribute in terms of formatting. The object is otherwise treated as a method.
return ret
def import_object(self):
# MethodDocumenter overrides import_object to do some sniffing in
# addition to just importing. But we do our own sniffing and just want
# the import, so we un-override it.
ret = ClassLevelDocumenter.import_object(self)
# Use 'inspect.getattr_static' to properly detect class or static methods.
# This also resolves the MRO entries for subclasses.
obj = inspect.getattr_static(self.parent, self.object_name)
# autodoc likes to re-use dicts here for some reason (!?!)
self.options = Options(self.options)
update_with_sniffed_options(obj, self.options)
# Replicate the special ordering hacks in
# MethodDocumenter.import_object
if "classmethod" in self.options or "staticmethod" in self.options:
self.member_order -= 1
return ret
def import_object(self):
# MethodDocumenter overrides import_object to do some sniffing in
# addition to just importing. But we do our own sniffing and just want
# the import, so we un-override it.
ret = ClassLevelDocumenter.import_object(self)
# If you have a classmethod or staticmethod, then
#
# Class.__dict__["name"]
#
# returns the classmethod/staticmethod object, but
#
# getattr(Class, "name")
#
# returns a regular function. We want to detect
# classmethod/staticmethod, so we need to go through __dict__.
obj = self.parent.__dict__.get(self.object_name)
update_with_sniffed_options(obj, self.options)
# Replicate the special ordering hacks in
# MethodDocumenter.import_object
if "classmethod" in self.options or "staticmethod" in self.options:
self.member_order -= 1
return ret
def iad_add_directive_header(self, sig):
ClassLevelDocumenter.add_directive_header(self, sig)
def add_directive_header(self, sig):
ClassLevelDocumenter.add_directive_header(self, sig)
def add_content(self, more_content, no_docstring=False):
""" Never try to get a docstring from the trait."""
ClassLevelDocumenter.add_content(self, more_content, no_docstring=True)
def add_content(self, more_content, no_docstring=False):
""" Never try to get a docstring from the trait."""
ClassLevelDocumenter.add_content(self, more_content,
no_docstring=True)
