def document_members(self, all_members=False):
"""Prepare environment for automatic device documentation"""
if all_members:
self.options.member_order = 'groupwise'
self.env.config.autodevice = True
TangoItemDocumenter.reset()
ClassDocumenter.document_members(self, all_members)
def generate_class_autodoc(app, cls):
ad = AutoDirective(
name="autoclass",
arguments=[FULL_NAMES[cls]],
options={"noindex": True},
content=StringList([], items=[]),
lineno=0,
content_offset=1,
block_text="",
state=None,
state_machine=None,
)
ad.env = BuildEnvironment(app)
ad.genopt = Options(noindex=True)
ad.filename_set = set()
ad.result = ViewList()
documenter = ClassDocumenter(ad, ad.arguments[0])
documenter.generate(all_members=True)
with open(OUTPUT_FILES[cls], "w") as fid:
fid.write(cls + '\n')
fid.write(''.join(['='] * len(cls)) + '\n')
for line in ad.result:
fid.write(line + "\n")
def add_content(self, more_content, no_docstring=False):
ClassDocumenter.add_content(self, more_content, no_docstring)
obj = self.object
try:
binding_class = make_class_ref(obj._binding_class)
except AttributeError:
binding_class = "<undefined>"
self.add_line("| XML binding class: %s\n" % binding_class, "<autoentity>")
def add_content(self, *args, **kwargs): """ Add content from docstrings, attribute documentation and user. """ ClassDocumenter.add_content(self, *args, **kwargs) if not self.doc_as_attr: self.add_autosummary()
def add_content(self, more_content, no_docstring=False):
ClassDocumenter.add_content(self, more_content, no_docstring)
obj = self.object
try:
binding_class = make_class_ref(obj._binding_class)
except AttributeError:
binding_class = "<undefined>"
self.add_line("| XML binding class: %s\n" % binding_class, "<autoentity>")
def add_directive_header(self, sig):
ClassDocumenter.add_directive_header(self, sig)
# add inheritance info, if wanted
if not self.doc_as_attr:
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`' % (b.__module__, b.__name__)
for b in self.object.__bases__ if b is not object]
if bases:
self.add_line(' **Bases:** %s' % ', '.join(bases),
'<autodoc>')
def __init__(self, *args, **kwargs):
super(BlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
sptr_name = self.name + '_sptr'
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive,
sptr_name,
indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
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
# Add header
if all_members:
self.indent, temp = '', self.indent
section = self.section.format(self.object.__name__)
self.add_line(section, '<autodoc>')
self.add_line("*" * len(section), '<autodoc>')
self.indent = temp
# Generate documentation
ClassDocumenter.generate(self, more_content, real_modname,
check_module, all_members)
def add_directive_header(self, sig):
ClassDocumenter.add_directive_header(self, sig)
# add inheritance info, if wanted
if not self.doc_as_attr:
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`' % (b.__module__, b.__name__)
for b in self.object.__bases__ if b is not object
]
if bases:
self.add_line(' **Bases:** %s' % ', '.join(bases),
'<autodoc>')
def document_members(self, all_members=False):
if not hasattr(self.object, 'parameters'):
return ClassDocumenter.document_members(self, all_members)
if self.doc_as_attr:
return
orig_indent = self.indent
myclsname = self.object.__module__ + '.' + self.object.__name__
basecmdinfo = []
baseparaminfo = []
n = 0
if isinstance(self.object.parameters, property):
return ClassDocumenter.document_members(self, all_members)
for param, info in sorted(self.object.parameters.items()):
if info.classname is not None and info.classname != myclsname:
baseparaminfo.append((param, info))
continue
if n == 0:
self.add_line('', '<autodoc>')
self.add_line('**Parameters**', '<autodoc>')
self.add_line('', '<autodoc>')
if isinstance(info.type, type):
ptype = info.type.__name__
else:
ptype = info.type.__doc__ or '?'
addinfo = [ptype]
if info.default == None: addinfo.append('mandatory in setup')
self.add_line(
'.. parameter:: %s : %s' % (param, ', '.join(addinfo)),
'<autodoc>')
self.add_line('', '<autodoc>')
self.indent += self.content_indent
descr = info.description or ''
descr = descr.decode('utf-8')
if descr and not descr.endswith('.'): descr += '.'
if info.default is not None:
descr += ' Default value: ``%r``.' % (info.default, )
self.add_line(descr, '<%s.%s description>' % (self.object, param))
self.add_line('', '<autodoc>')
self.indent = orig_indent
n += 1
if baseparaminfo:
self.add_line('', '<autodoc>')
self.add_line(
'Parameters inherited from the base classes: ' +
', '.join('`~%s.%s`' % (info.classname or '', name)
for (name, info) in baseparaminfo), '<autodoc>')
def document_members(self, all_members=False):
if not hasattr(self.object, 'parameters'):
return ClassDocumenter.document_members(self, all_members)
if self.doc_as_attr:
return
orig_indent = self.indent
myclsname = self.object.__module__ + '.' + self.object.__name__
basecmdinfo = []
baseparaminfo = []
n = 0
if isinstance(self.object.parameters, property):
return ClassDocumenter.document_members(self, all_members)
for param, info in sorted(self.object.parameters.items()):
if info.classname is not None and info.classname != myclsname:
baseparaminfo.append((param, info))
continue
if n == 0:
self.add_line('', '<autodoc>')
self.add_line('**Parameters**', '<autodoc>')
self.add_line('', '<autodoc>')
if isinstance(info.type, type):
ptype = info.type.__name__
else:
ptype = info.type.__doc__ or '?'
addinfo = [ptype]
if info.default == None: addinfo.append('mandatory in setup')
self.add_line('.. parameter:: %s : %s' %
(param, ', '.join(addinfo)), '<autodoc>')
self.add_line('', '<autodoc>')
self.indent += self.content_indent
descr = info.description or ''
descr = descr.decode('utf-8')
if descr and not descr.endswith('.'): descr += '.'
if info.default is not None:
descr += ' Default value: ``%r``.' % (info.default,)
self.add_line(descr, '<%s.%s description>' % (self.object, param))
self.add_line('', '<autodoc>')
self.indent = orig_indent
n += 1
if baseparaminfo:
self.add_line('', '<autodoc>')
self.add_line('Parameters inherited from the base classes: ' +
', '.join('`~%s.%s`' % (info.classname or '', name)
for (name, info) in baseparaminfo), '<autodoc>')
def __init__(self, *args, **kwargs):
super(OldBlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
bits = self.name.split('.')
if len(bits) != 3 or bits[0] != 'gnuradio':
raise ValueError(
"expected name to be of form gnuradio.x.y but it is {0}".
format(self.name))
sptr_name = 'gnuradio.{0}.{0}_{1}_sptr'.format(bits[1], bits[2])
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive,
sptr_name,
indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
def __init__(self, *args, **kwargs):
super(BlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
sptr_name = self.name + '_sptr'
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive, sptr_name, indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
class BlockDocumenter(FunctionDocumenter):
"""
Specialized Documenter subclass for new style gnuradio blocks.
It merges together the documentation for the generator function (e.g. wavelet.squash_ff)
with the wrapped sptr (e.g. wavelet.squash_ff_sptr) to keep the documentation
tidier.
"""
objtype = 'block'
directivetype = 'function'
# Don't want to use this for generic functions for give low priority.
priority = -10
def __init__(self, *args, **kwargs):
super(BlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
sptr_name = self.name + '_sptr'
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive, sptr_name, indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
def document_members(self, *args, **kwargs):
return self.classdoccer.document_members(*args, **kwargs)
class OldBlockDocumenter(FunctionDocumenter):
"""
Specialized Documenter subclass for gnuradio blocks.
It merges together the documentation for the generator function (e.g. gr.head)
with the wrapped sptr (e.g. gr.gr_head_sptr) to keep the documentation
tidier.
"""
objtype = 'oldblock'
directivetype = 'function'
# Don't want to use this for generic functions for give low priority.
priority = -10
def __init__(self, *args, **kwargs):
super(OldBlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
bits = self.name.split('.')
if len(bits) != 3 or bits[0] != 'gnuradio':
raise ValueError("expected name to be of form gnuradio.x.y but it is {0}".format(self.name))
sptr_name = 'gnuradio.{0}.{0}_{1}_sptr'.format(bits[1], bits[2])
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive, sptr_name, indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
def document_members(self, *args, **kwargs):
return self.classdoccer.document_members(*args, **kwargs)
class BlockDocumenter(FunctionDocumenter):
"""
Specialized Documenter subclass for new style gnuradio blocks.
It merges together the documentation for the generator function (e.g. wavelet.squash_ff)
with the wrapped sptr (e.g. wavelet.squash_ff_sptr) to keep the documentation
tidier.
"""
objtype = 'block'
directivetype = 'function'
# Don't want to use this for generic functions for give low priority.
priority = -10
def __init__(self, *args, **kwargs):
super(BlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
sptr_name = self.name + '_sptr'
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive,
sptr_name,
indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
def document_members(self, *args, **kwargs):
return self.classdoccer.document_members(*args, **kwargs)
class OldBlockDocumenter(FunctionDocumenter):
"""
Specialized Documenter subclass for gnuradio blocks.
It merges together the documentation for the generator function (e.g. gr.head)
with the wrapped sptr (e.g. gr.gr_head_sptr) to keep the documentation
tidier.
"""
objtype = 'oldblock'
directivetype = 'function'
# Don't want to use this for generic functions for give low priority.
priority = -10
def __init__(self, *args, **kwargs):
super(OldBlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
bits = self.name.split('.')
if len(bits) != 3 or bits[0] != 'gnuradio':
raise ValueError(
"expected name to be of form gnuradio.x.y but it is {0}".
format(self.name))
sptr_name = 'gnuradio.{0}.{0}_{1}_sptr'.format(bits[1], bits[2])
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive,
sptr_name,
indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
def document_members(self, *args, **kwargs):
return self.classdoccer.document_members(*args, **kwargs)
def test_can_document_member(self):
# Regression test for enthought/traits#1238
with self.create_directive() as directive:
class_documenter = ClassDocumenter(
directive, __name__ + ".FindTheTraits"
)
class_documenter.parse_name()
class_documenter.import_object()
self.assertTrue(
TraitDocumenter.can_document_member(
INSTANCEATTR, "an_int", True, class_documenter,
)
)
self.assertTrue(
TraitDocumenter.can_document_member(
INSTANCEATTR, "another_int", True, class_documenter,
)
)
self.assertFalse(
TraitDocumenter.can_document_member(
INSTANCEATTR, "magic_number", True, class_documenter,
)
)
self.assertFalse(
TraitDocumenter.can_document_member(
INSTANCEATTR, "not_a_trait", True, class_documenter,
)
)
def add_content(self, more_content, no_docstring=False):
ClassDocumenter.add_content(self, more_content, no_docstring)
obj = self.object
self.add_line(':Properties:', '<stixattr>')
for prop_name, prop in obj._properties.items():
# Skip 'type'
if prop_name == 'type':
continue
# Add metadata about the property
prop_type = get_property_type(prop)
if prop_type == 'List':
prop_type = 'List of %ss' % get_property_type(prop.contained)
if prop.required:
prop_type += ', required'
if 'Timestamp' in prop_type and hasattr(prop, 'default'):
prop_type += ', default: current date/time'
prop_str = '**%s** (*%s*)' % (prop_name, prop_type)
self.add_line(' - %s' % prop_str, '<stixattr>')
self.add_line('', '<stixattr>')
def __init__(self, *args, **kwargs):
super(OldBlockDocumenter, self).__init__(*args, **kwargs)
# Get class name
bits = self.name.split('.')
if len(bits) != 3 or bits[0] != 'gnuradio':
raise ValueError("expected name to be of form gnuradio.x.y but it is {0}".format(self.name))
sptr_name = 'gnuradio.{0}.{0}_{1}_sptr'.format(bits[1], bits[2])
# Create a Class Documenter to create documentation for the classes members.
self.classdoccer = ClassDocumenter(self.directive, sptr_name, indent=self.content_indent)
self.classdoccer.doc_as_attr = False
self.classdoccer.real_modname = self.classdoccer.get_real_modname()
self.classdoccer.options.members = ALL
self.classdoccer.options.exclude_members = common_block_members
self.classdoccer.parse_name()
self.classdoccer.import_object()
def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
return ClassDocumenter.get_object_members(self, want_all)
def document_members(self, all_members=False):
if not issubclass(self.object, Device) and \
not issubclass(self.object, DeviceMixinBase) and \
not issubclass(self.object, NicosWidget):
return ClassDocumenter.document_members(self, all_members)
if self.doc_as_attr:
return
orig_indent = self.indent
if issubclass(self.object, NicosWidget):
self._format_properties(self.object, orig_indent)
return
if hasattr(self.object, 'methods'):
self._format_methods(self.object.methods.items(), orig_indent)
if getattr(self.object, 'attached_devices', None):
self._format_attached_devices(self.object.attached_devices.items())
if not hasattr(self.object, 'parameters'):
return
if not hasattr(self.env, 'nicos_all_devices'):
self.env.nicos_all_devices = {}
docstr = '\n'.join(prepare_docstring(self.object.__doc__ or ''))
self.env.nicos_all_devices[self.object.__name__,
self.object.__module__] = {
'docname': self.env.docname,
'name': self.object.__name__,
'module': self.env.ref_context.get(
'py:module',
self.object.__module__),
'blurb': docstr.split('\n\n')[0],
}
mandatoryparaminfo = []
optionalparaminfo = []
baseparaminfo = []
myclsname = self.object.__module__ + '.' + self.object.__name__
for param, info in sorted(self.object.parameters.items()):
if not info.userparam:
continue
if info.classname is not None and info.classname != myclsname:
baseparaminfo.append((param, info))
info.derived = True
else:
info.derived = False
if info.mandatory:
mandatoryparaminfo.append((param, info))
else:
optionalparaminfo.append((param, info))
if mandatoryparaminfo or optionalparaminfo:
self.add_line('', '<autodoc>')
self.add_line('**Parameters**', '<autodoc>')
self.add_line('', '<autodoc>')
if mandatoryparaminfo:
self.add_line('', '<autodoc>')
self.add_line('*Mandatory*', '<autodoc>')
self.add_line('', '<autodoc>')
self._format_parameters(mandatoryparaminfo, orig_indent)
if optionalparaminfo:
self.add_line('', '<autodoc>')
self.add_line('*Optional*', '<autodoc>')
self.add_line('', '<autodoc>')
self._format_parameters(optionalparaminfo, orig_indent)
if baseparaminfo:
self.add_line('', '<autodoc>')
self.add_line(
'Parameters inherited from the base classes are: ' +
', '.join('`~%s.%s`' % (info.classname or '', name)
for (name, info) in baseparaminfo), '<autodoc>')
def import_object(self):
reload(import_module(self.modname))
return ClassDocumenter.import_object(self)