Ejemplo n.º 1
0
 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)
Ejemplo n.º 2
0
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")
Ejemplo n.º 3
0
    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>")
Ejemplo n.º 4
0
	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()
Ejemplo n.º 5
0
    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>")
Ejemplo n.º 6
0
    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>')
Ejemplo n.º 7
0
 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()
Ejemplo n.º 8
0
 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)
Ejemplo n.º 9
0
    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>')
Ejemplo n.º 10
0
    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>')
Ejemplo n.º 11
0
    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>')
Ejemplo n.º 12
0
 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()
Ejemplo n.º 13
0
 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()
Ejemplo n.º 14
0
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)
Ejemplo n.º 15
0
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)
Ejemplo n.º 16
0
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)
Ejemplo n.º 17
0
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)
Ejemplo n.º 18
0
    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,
                )
            )
Ejemplo n.º 19
0
    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>')
Ejemplo n.º 20
0
 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()
Ejemplo n.º 21
0
 def get_object_members(self, want_all: bool) -> Tuple[bool, ObjectMembers]:
     return ClassDocumenter.get_object_members(self, want_all)
Ejemplo n.º 22
0
    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>')
Ejemplo n.º 23
0
 def import_object(self):
     reload(import_module(self.modname))
     return ClassDocumenter.import_object(self)