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_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()
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 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)