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)
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 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 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>')
