Exemple #1
0
    def make_content(self, all_members):
        ret = nodes.section()
        doc = self.item
        if doc.doc:
            self.directive.state.nested_parse(to_list(doc.doc), 0, ret)

        check_parameters(self, doc)

        params, subtypes = extract_subtypes(self.item.name, self.item)
        rdoc = doc.return_val.doc
        rtype = doc.return_val.type
        if params or rtype or rdoc:
            with addto(ret, nodes.field_list()) as fields:
                if params:
                    with addto(fields, nodes.field()) as field:
                        field += nodes.field_name('Parameters', 'Parameters')
                        with addto(field, nodes.field_body()) as body,\
                             addto(body, nodes.bullet_list()) as holder:
                            holder.extend(make_parameters(params, mod=doc['sourcemodule'].name))
                if rdoc:
                    with addto(fields, nodes.field()) as field:
                        field += nodes.field_name("Returns", "Returns")
                        with addto(field, nodes.field_body()) as body,\
                             addto(body, nodes.paragraph()) as p:
                            p += nodes.inline(rdoc, rdoc)
                if rtype:
                    with addto(fields, nodes.field()) as field:
                        field += nodes.field_name("Return Type", "Return Type")
                        with addto(field, nodes.field_body()) as body, \
                             addto(body, nodes.paragraph()) as p:
                            p += make_types(rtype, mod=doc['sourcemodule'].name)

        ret += self.document_subtypes(subtypes)

        return ret.children
Exemple #2
0
 def _build_markup(self):
     field_list = nodes.field_list()
     item = nodes.paragraph()
     item.append(field_list)
     if 'branch' in self.options:
         name = nodes.field_name(text="Branch")
         body = nodes.field_body()
         body.append(nodes.emphasis(text=self.branch_name))
         field = nodes.field()
         field += [name, body]
         field_list.append(field)
     if 'commit' in self.options:
         name = nodes.field_name(text="Commit")
         body = nodes.field_body()
         if 'no_github_link' in self.options:
             body.append(self._commit_text_node())
         else:
             body.append(self._github_link())
         field = nodes.field()
         field += [name, body]
         field_list.append(field)
     if 'uncommitted' in self.options and self.repo.is_dirty():
         item.append(nodes.warning('', nodes.inline(
             text="There were uncommitted changes when this was compiled."
         )))
     if 'untracked' in self.options and self.repo.untracked_files:
         item.append(nodes.warning('', nodes.inline(
             text="There were untracked files when this was compiled."
         )))
     return [item]
Exemple #3
0
def handle_doc_fields(node):
    # don't traverse, only handle field lists that are immediate children
    for child in node.children:
        if not isinstance(child, nodes.field_list):
            continue
        params = None
        param_nodes = {}
        param_types = {}
        new_list = nodes.field_list()
        for field in child:
            fname, fbody = field
            try:
                typ, obj = fname.astext().split(None, 1)
                typ = doc_fields_with_arg[typ]
                if len(fbody.children) == 1 and \
                   isinstance(fbody.children[0], nodes.paragraph):
                    children = fbody.children[0].children
                else:
                    children = fbody.children
                if typ == 'param':
                    if not params:
                        pfield = nodes.field()
                        pfield += nodes.field_name('Parameters', 'Parameters')
                        pfield += nodes.field_body()
                        params = nodes.bullet_list()
                        pfield[1] += params
                        new_list += pfield
                    dlitem = nodes.list_item()
                    dlpar = nodes.paragraph()
                    dlpar += nodes.emphasis(obj, obj)
                    dlpar += nodes.Text(' -- ', ' -- ')
                    dlpar += children
                    param_nodes[obj] = dlpar
                    dlitem += dlpar
                    params += dlitem
                elif typ == 'type':
                    param_types[obj] = fbody.astext()
                else:
                    fieldname = typ + ' ' + obj
                    nfield = nodes.field()
                    nfield += nodes.field_name(fieldname, fieldname)
                    nfield += nodes.field_body()
                    nfield[1] += fbody.children
                    new_list += nfield
            except (KeyError, ValueError):
                fnametext = fname.astext()
                try:
                    typ = doc_fields_without_arg[fnametext]
                except KeyError:
                    # at least capitalize the field name
                    typ = fnametext.capitalize()
                fname[0] = nodes.Text(typ)
                new_list += field
        for param, type in param_types.iteritems():
            if param in param_nodes:
                param_nodes[param].insert(1, nodes.Text(' (%s)' % type))
        child.replace_self(new_list)
Exemple #4
0
    def run(self):
        self.cabal_meta = self.get_meta()
        result = super(CabalObject, self).run()

        if self.cabal_meta.since is not None \
           or self.cabal_meta.deprecated is not None:

            #find content part of description
            for item in result:
                if isinstance(item, addnodes.desc):
                    desc = item
                    break
            else:
                return result

            for item in desc:
                if isinstance(item, addnodes.desc_content):
                    contents = item
                    break
            else:
                return result

            # find exsting field list and add to it
            # or create new one
            for item in contents:
                if isinstance(item, nodes.field_list):
                    field_list = item
                    break
            else:
                field_list = nodes.field_list('')
                contents.insert(0, field_list)


            if self.cabal_meta.since is not None:
                #docutils horror
                field = nodes.field('')
                field_name = nodes.field_name('Since', 'Since')
                since = 'Cabal ' + str(self.cabal_meta.since)
                field_body = nodes.field_body(since, nodes.paragraph(since, since))
                field += field_name
                field += field_body
                field_list.insert(0, field)

            if self.cabal_meta.deprecated is not None:
                field = nodes.field('')
                field_name = nodes.field_name('Deprecated', 'Deprecated')
                if isinstance(self.cabal_meta.deprecated, StrictVersion):
                    since = 'Cabal ' + str(self.cabal_meta.deprecated)
                else:
                    since = ''

                field_body = nodes.field_body(since, nodes.paragraph(since, since))
                field += field_name
                field += field_body
                field_list.insert(0, field)

        return result
Exemple #5
0
    def make_field(self, field_name, field_body):
        """Fill content into nodes.

        :param string field_name: Field name of the field
        :param field_name: Field body if the field
        :type field_name: str or instance of docutils.nodes
        :return: field instance filled with given name and body
        :rtype: nodes.field

        """
        name = nodes.field_name()
        name += nodes.Text(field_name)

        paragraph = nodes.paragraph()
        if isinstance(field_body, six.string_types):
            # This is the case when field_body is just a string:
            paragraph += nodes.Text(field_body)
        else:
            # This is the case when field_body is a complex node:
            # useful when constructing nested field lists
            paragraph += field_body

        body = nodes.field_body()
        body += paragraph

        field = nodes.field()
        field.extend([name, body])
        return field
 def run(self):
     try:
         fields = self.future_fields.get(timeout=30)
     except Queue.Empty:
         return [self.state_machine.reporter.error(
             "Timed out while fetching fields related to action [%s]" % self.arguments[0]
         )]
     if fields is None:
         return [self.state_machine.reporter.warning(
             "Could not find any field related to the action [%s]" % self.arguments[0]
         )]
     whitelist = set(self.options.get('only', '').split())
     return [nodes.field_list('', *(
         nodes.field('',
             nodes.field_name(text=v['string'] or k),
             nodes.field_body('',
                 # keep help formatting around (e.g. newlines for lists)
                 nodes.line_block('', *(
                     nodes.line(text=line)
                     for line in v['help'].split('\n')
                 ))
             )
         )
         for k, v in fields.iteritems()
         # if there's a whitelist, only display whitelisted fields
         if not whitelist or k in whitelist
         # only display if there's a help text
         if v.get('help')
     ))]
Exemple #7
0
 def make_field(self, name, body):
     if not isinstance(body, nodes.Node):
         body = nodes.paragraph(text=body)
     return nodes.field(
         '',
         nodes.field_name(text=name),
         nodes.field_body('', body))
Exemple #8
0
    def make_field(self, types, domain, items):
        def handle_item(fieldarg, content):
            par = nodes.paragraph()
            par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
                                       addnodes.literal_strong))
            if fieldarg in types:
                par += nodes.Text(' (')
                # NOTE: using .pop() here to prevent a single type node to be
                # inserted twice into the doctree, which leads to
                # inconsistencies later when references are resolved
                fieldtype = types.pop(fieldarg)
                if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                    typename = u''.join(n.astext() for n in fieldtype)
                    par.extend(self.make_xrefs(self.typerolename, domain, typename,
                                               addnodes.literal_emphasis))
                else:
                    par += fieldtype
                par += nodes.Text(')')
            par += nodes.Text(' -- ')
            par += content
            return par

        fieldname = nodes.field_name('', self.label)
        if len(items) == 1 and self.can_collapse:
            fieldarg, content = items[0]
            bodynode = handle_item(fieldarg, content)
        else:
            bodynode = self.list_type()
            for fieldarg, content in items:
                bodynode += nodes.list_item('', handle_item(fieldarg, content))
        fieldbody = nodes.field_body('', bodynode)
        return nodes.field('', fieldname, fieldbody)
Exemple #9
0
def process_motor_nodes(app, doctree):
    # Search doctree for Motor's methods and attributes whose docstrings were
    # copied from PyMongo, and fix them up for Motor:
    #   1. Add a 'callback' param (sometimes optional, sometimes required) to
    #      all async methods. If the PyMongo method took no params, we create
    #      a parameter-list from scratch, otherwise we edit PyMongo's list.
    #   2. Remove all version annotations like "New in version 2.0" since
    #      PyMongo's version numbers are meaningless in Motor's docs.
    #   3. Remove "seealso" directives that reference PyMongo's docs.
    #
    # We do this here, rather than by registering a callback to Sphinx's
    # 'autodoc-process-signature' event, because it's way easier to handle the
    # parsed doctree before it's turned into HTML than it is to update the RST.
    for objnode in doctree.traverse(desc):
        if objnode["objtype"] in ("method", "attribute"):
            signature_node = find_by_path(objnode, [desc_signature])[0]
            name = ".".join([signature_node["module"], signature_node["fullname"]])

            assert name.startswith("motor.")
            obj_motor_info = motor_info.get(name)
            if obj_motor_info:
                desc_content_node = find_by_path(objnode, [desc_content])[0]
                if obj_motor_info.get("is_async_method"):
                    try:
                        # Find the parameter list, a bullet_list instance
                        parameters_node = find_by_path(desc_content_node, [field_list, field, field_body, bullet_list])[
                            0
                        ]
                    except IndexError:
                        # PyMongo method has no parameters, create an empty
                        # params list
                        parameters_node = bullet_list()
                        parameters_field_list_node = field_list(
                            "", field("", field_name("", "Parameters "), field_body("", parameters_node))
                        )

                        desc_content_node.append(parameters_field_list_node)

                    insert_callback(parameters_node)

                    callback_future_text = "If a callback is passed, returns None, else returns a" " Future."

                    desc_content_node.append(paragraph("", Text(callback_future_text)))

                if obj_motor_info["is_pymongo_docstring"]:
                    # Remove all "versionadded", "versionchanged" and
                    # "deprecated" directives from the docs we imported from
                    # PyMongo
                    version_nodes = find_by_path(desc_content_node, [versionmodified])

                    for version_node in version_nodes:
                        version_node.parent.remove(version_node)

                    # Remove all "seealso" directives that contain :doc:
                    # references from PyMongo's docs
                    seealso_nodes = find_by_path(desc_content_node, [seealso])

                    for seealso_node in seealso_nodes:
                        if 'reftype="doc"' in str(seealso_node):
                            seealso_node.parent.remove(seealso_node)
Exemple #10
0
    def make_content(self, all_members):
        doc = self.item
        content = addnodes.desc_content()

        if doc.exports or doc.dependencies:
            with addto(content, nodes.field_list()) as fields:
                if doc.exports:
                    with addto(fields, nodes.field()) as field:
                        field += nodes.field_name('Exports', 'Exports')
                        with addto(field, nodes.field_body()) as body:
                            ref = doc['exports'] # warning: not the same as doc.exports
                            label = ref or '<anonymous>'
                            link = addnodes.pending_xref(
                                ref, nodes.paragraph(ref, label),
                                refdomain='js',
                                reftype='any',
                                reftarget=ref,
                            )
                            link['js:module'] = doc.name
                            body += link

                if doc.dependencies:
                    with addto(fields, nodes.field()) as field:
                        self.make_dependencies(field, doc)

        if doc.doc:
            # FIXME: source offset
            self.directive.state.nested_parse(to_list(doc.doc, source=doc['sourcefile']), 0, content)

        self.directive.state.nested_parse(self.directive.content, 0, content)

        content += self.document_properties(all_members)

        return content
Exemple #11
0
 def make_field(self, types, domain, items):
     fieldname = nodes.field_name('', self.label)
     listnode = self.list_type()
     for fieldarg, content in items:
         listnode += nodes.list_item('', nodes.paragraph('', '', *content))
     fieldbody = nodes.field_body('', listnode)
     return nodes.field('', fieldname, fieldbody)
Exemple #12
0
 def make_field(self, types, domain, item):
     fieldarg, content = item
     fieldname = nodes.field_name("", self.label)
     if fieldarg:
         fieldname += nodes.Text(" ")
         fieldname += self.make_xref(self.rolename, domain, fieldarg, nodes.Text)
     fieldbody = nodes.field_body("", nodes.paragraph("", "", *content))
     return nodes.field("", fieldname, fieldbody)
def bullet_list_field(key, value):
    items = []
    for item in value:
        item_p = nodes.paragraph(item, item)
        items.append(nodes.list_item('', item_p))
    bullet_list = nodes.bullet_list('', *items)
    field_name = nodes.field_name(key, key)
    field_body = nodes.field_body('', bullet_list)
    return nodes.field('', field_name, field_body)
Exemple #14
0
 def _parse_field(self, tree, children):
     numargs = 0
     while tree.childNodes[numargs+1].tagName == 'arg': numargs += 1
     tag = children[0]
     args = children[1:1+numargs]
     body = children[1+numargs:]
     name = nodes.field_name('','', *children[:1+numargs])
     body = nodes.field_body('', *children[1+numargs:])
     return (name, body)
Exemple #15
0
def fieldlist(fields, *classes):
    node = nodes.field_list('')
    node['classes'].extend(classes)
    for name, value in fields:
        node += nodes.field('',
            nodes.field_name('', name),
            nodes.field_body('', nodes.paragraph('', value)),
        )
    return node
 def make_field(self, domain, items):
     fieldname = nodes.field_name('', self.label)
     listnode = self.list_type()
     for content in items:
         par = nodes.paragraph()
         par += content
         listnode += nodes.list_item('', par)
     fieldbody = nodes.field_body('', listnode)
     return nodes.field('', fieldname, fieldbody)
Exemple #17
0
    def make_params(self, params):
        if not params:
            return []

        ret = nodes.field('', nodes.field_name('Parameters', 'Parameters'))
        with addto(ret, nodes.field_body()) as body,\
             addto(body, nodes.bullet_list()) as holder:
            holder += make_parameters(params, mod=self.modname)
        return ret
 def make_field(self, tag, value):
     field = nodes.field()
     field.append(nodes.field_name(text=tag))
     body = nodes.field_body()
     if isinstance(value, basestring):
         body.append(sphinx.addnodes.compact_paragraph(text=value))
     else:
         body.append(value)
     field.append(body)
     return field
 def make_field(self, types, domain, items, **kwargs):
     
     fieldname = nodes.field_name('', self.label)
     #par = Field.make_field(self, types, domain, items[0])
     par = nodes.paragraph()
     for i,item in enumerate(items):
         if i: par += nodes.Text(' ')
         par += item[1]#Field.make_field(self, types, domain, item)
     fieldbody = nodes.field_body('', par)
     return nodes.field('', fieldname, fieldbody)
Exemple #20
0
 def make_field(self, types, domain, items):
     fieldname = nodes.field_name('', self.label)
     if len(items) == 1 and self.can_collapse:
         return Field.make_field(self, types, domain, items[0])
     bodynode = nodes.paragraph()
     for i, (fieldarg, content) in enumerate(items):
         bodynode += nodes.Text(', ') if i else None
         bodynode += self.make_xref(self.bodyrolename, domain,
                                    content[0].astext(), nodes.Text)
     fieldbody = nodes.field_body('', bodynode)
     return nodes.field('', fieldname, fieldbody)
 def make_field(self, types, domain, items):
     if len(items) == 1 and self.can_collapse:
         super(NoArgGroupedField, self).make_field(types, domain, items)
     fieldname = nodes.field_name("", self.label)
     listnode = self.list_type()
     for fieldarg, content in items:
         par = nodes.paragraph()
         par += content
         listnode += nodes.list_item("", par)
     fieldbody = nodes.field_body("", listnode)
     return nodes.field("", fieldname, fieldbody)
 def make_field(self, types, domain, items, env=None):
     fieldname = nodes.field_name('', self.label)
     listnode = self.list_type()
     if len(items) == 1 and self.can_collapse:
         return Field.make_field(self, types, domain, items[0])
     for fieldarg, content in items:
         par = nodes.paragraph()
         par += self.make_xref(self.rolename, domain, fieldarg, nodes.strong)
         listnode += nodes.list_item('', par)
     fieldbody = nodes.field_body('', listnode)
     return nodes.field('', fieldname, fieldbody)
Exemple #23
0
 def make_field(self, types, domain, item, env=None):
     fieldname = nodes.field_name('', self.label)
     backref = addnodes.pending_xref(
         '',
         refdomain="conda",
         reftype='requiredby', refexplicit=False,
         reftarget=env.ref_context['conda:package'],
         refdoc=env.docname
     )
     backref += nodes.inline('', '')
     fieldbody = nodes.field_body('', backref)
     return nodes.field('', fieldname, fieldbody)
Exemple #24
0
 def make_dependencies(self, field, doc):
     field += nodes.field_name("Depends On", "Depends On")
     with addto(field, nodes.field_body()) as body:
         with addto(body, nodes.bullet_list()) as deps:
             for dep in sorted(doc.dependencies):
                 ref = addnodes.pending_xref(
                     dep, nodes.paragraph(dep, dep),
                     refdomain='js',
                     reftype='module',
                     reftarget=dep,
                 )
                 deps += nodes.list_item(dep, ref)
 def run(self):
     field_list = nodes.field_list()
     for name, value in TAGS:
         fieldname = nodes.field_name()
         fieldname += nodes.Text(name)
         fieldbody = nodes.field_body()
         para = nodes.paragraph()
         para += nodes.Text(value)
         fieldbody += para
         field = nodes.field('', fieldname, fieldbody)
         field_list += field
     return [field_list]
Exemple #26
0
 def make_field(self, types, domain, items):
     fieldname = nodes.field_name('', self.label)
     listnode = self.list_type()
     for fieldarg, content in items:
         par = nodes.paragraph()
         par += self.make_xref(self.rolename, domain, fieldarg,
                               nodes.literal)
         if content and content[0].children:
             par += nodes.Text(' -- ')
             par += content
         listnode += nodes.list_item('', par)
     fieldbody = nodes.field_body('', listnode)
     return nodes.field('', fieldname, fieldbody)
Exemple #27
0
 def rfc2822_field(self, match):
     name = match.string[:match.string.find(':')]
     indented, indent, line_offset, blank_finish = \
           self.state_machine.get_first_known_indented(match.end(),
                                                       until_blank=1)
     fieldnode = nodes.field()
     fieldnode += nodes.field_name(name, name)
     fieldbody = nodes.field_body('\n'.join(indented))
     fieldnode += fieldbody
     if indented:
         self.nested_parse(indented, input_offset=line_offset,
                           node=fieldbody)
     return fieldnode, blank_finish
Exemple #28
0
 def make_field(self, types, domain, item):
     fieldarg, content = item
     fieldname = nodes.field_name("", self.label)
     if fieldarg:
         fieldname += nodes.Text(" ")
         fieldname += self.make_xref(self.rolename, domain, fieldarg, nodes.Text)
     if len(content) == 1 and (
         isinstance(content[0], nodes.Text)
         or (isinstance(content[0], nodes.inline) and len(content[0]) == 1 and isinstance(content[0][0], nodes.Text))
     ):
         content = [self.make_xref(self.bodyrolename, domain, content[0].astext(), contnode=content[0])]
     fieldbody = nodes.field_body("", nodes.paragraph("", "", *content))
     return nodes.field("", fieldname, fieldbody)
Exemple #29
0
 def transform(cls, node):
     split = node[0].rawsource.split(None, 2)
     type = None
     if len(split) == 3:
         name, type, value = split
     elif len(split) == 2:
         name, value = split
     else:
         raise Exception('Too Few arguments.')
     node.attributes['names'].append(name)
     if type:
         node.insert(1, field_type(type))
     node[0].replace_self(nodes.field_name(value, value))
Exemple #30
0
def process_motor_nodes(app, doctree):
    # Search doctree for Motor's methods and attributes whose docstrings were
    # copied from PyMongo, and fix them up for Motor:
    #   1. Add a 'callback' param (sometimes optional, sometimes required) to
    #      all async methods. If the PyMongo method took no params, we create
    #      a parameter-list from scratch, otherwise we edit PyMongo's list.
    #   2. Remove all version annotations like "New in version 2.0" since
    #      PyMongo's version numbers are meaningless in Motor's docs.
    #
    # We do this here, rather than by registering a callback to Sphinx's
    # 'autodoc-process-signature' event, because it's way easier to handle the
    # parsed doctree before it's turned into HTML than it is to update the RST.
    for objnode in doctree.traverse(desc):
        if objnode['objtype'] in ('method', 'attribute'):
            signature_node = find_by_path(objnode, [desc_signature])[0]
            name = '.'.join([
                signature_node['module'], signature_node['fullname']])

            assert name.startswith('motor.')
            obj_motor_info = motor_info.get(name)
            if obj_motor_info:
                desc_content_node = find_by_path(objnode, [desc_content])[0]
                if obj_motor_info.get('is_async_method'):
                    try:
                        # Find the parameter list, a bullet_list instance
                        parameters_node = find_by_path(desc_content_node,
                            [field_list, field, field_body, bullet_list])[0]
                    except IndexError:
                        # PyMongo method has no parameters, create an empty
                        # params list
                        parameters_node = bullet_list()
                        parameters_field_list_node = field_list('',
                            field('',
                                field_name('', 'Parameters '),
                                field_body('',
                                    parameters_node)))

                        desc_content_node.append(parameters_field_list_node)

                    insert_callback(
                        parameters_node, obj_motor_info['callback_required'])

                if obj_motor_info['is_pymongo_docstring']:
                    # Remove all "versionadded", "versionchanged" and
                    # "deprecated" directives from the docs we imported from
                    # PyMongo
                    version_nodes = find_by_path(
                        desc_content_node, [versionmodified])

                    for version_node in version_nodes:
                        version_node.parent.remove(version_node)
Exemple #31
0
    def make_field(self,
                   types,     # type: Dict[unicode, List[nodes.Node]]
                   domain,    # type: unicode
                   item,      # type: Tuple
                   env=None,  # type: BuildEnvironment
                   ):
        # type: (...) -> nodes.field
        fieldarg, content = item
        fieldname = nodes.field_name('', self.label)
        if fieldarg:
            fieldname += nodes.Text(' ')
            fieldname.extend(self.make_xrefs(self.rolename, domain,
                                             fieldarg, nodes.Text, env=env))

        if len(content) == 1 and (
                isinstance(content[0], nodes.Text) or
                (isinstance(content[0], nodes.inline) and len(content[0]) == 1 and
                 isinstance(content[0][0], nodes.Text))):
            content = self.make_xrefs(self.bodyrolename, domain,
                                      content[0].astext(), contnode=content[0], env=env)
        fieldbody = nodes.field_body('', nodes.paragraph('', '', *content))
        return nodes.field('', fieldname, fieldbody)
Exemple #32
0
    def make_field(
        self,
        types: Dict[str, List[nodes.Node]],
        domain: str,
        items: Tuple[str, List[nodes.inline]],
        env: BuildEnvironment = None
    ) -> nodes.field:
        def makerefs(rolename, name, node):
            return self.make_xrefs(rolename, domain, name, node, env=env)

        def handle_item(fieldarg: str, content: List[nodes.inline]) -> nodes.definition_list_item:
            head = nodes.term()
            head += makerefs(self.rolename, fieldarg, addnodes.literal_strong)
            fieldtype = types.pop(fieldarg, None)
            if fieldtype is not None:
                head += nodes.Text(' : ')
                if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                    text_node, = fieldtype  # type: nodes.Text
                    head += makerefs(self.typerolename, text_node.astext(), addnodes.literal_emphasis)
                    #typename = ''.join(n.astext() for n in fieldtype)
                    #head += makerefs(self.typerolename, typename, addnodes.literal_emphasis)
                else:
                    head += fieldtype

            body_content = nodes.paragraph('', '', *content)
            body = nodes.definition('', body_content)

            return nodes.definition_list_item('', head, body)

        fieldname = nodes.field_name('', self.label)
        if len(items) == 1 and self.can_collapse:
            fieldarg, content = items[0]
            bodynode = handle_item(fieldarg, content)
        else:
            bodynode = self.list_type()
            for fieldarg, content in items:
                bodynode += handle_item(fieldarg, content)
        fieldbody = nodes.field_body('', bodynode)
        return nodes.field('', fieldname, fieldbody)
Exemple #33
0
    def make_field(self,
                   types,     # type: Dict[str, List[nodes.Node]]
                   domain,    # type: str
                   items,     # type: Tuple
                   env=None,  # type: BuildEnvironment
                   ):
        # type: (...) -> nodes.field
        def handle_item(fieldarg, content):
            # type: (str, str) -> nodes.paragraph
            par = nodes.paragraph()
            par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
                                       addnodes.literal_strong, env=env))
            if fieldarg in types:
                par += nodes.Text(' (')
                # NOTE: using .pop() here to prevent a single type node to be
                # inserted twice into the doctree, which leads to
                # inconsistencies later when references are resolved
                fieldtype = types.pop(fieldarg)
                if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                    typename = fieldtype[0].astext()
                    par.extend(self.make_xrefs(self.typerolename, domain, typename,
                                               addnodes.literal_emphasis, env=env))
                else:
                    par += fieldtype
                par += nodes.Text(')')
            par += nodes.Text(' -- ')
            par += content
            return par

        fieldname = nodes.field_name('', self.label)
        if len(items) == 1 and self.can_collapse:
            fieldarg, content = items[0]
            bodynode = handle_item(fieldarg, content)  # type: nodes.Node
        else:
            bodynode = self.list_type()
            for fieldarg, content in items:
                bodynode += nodes.list_item('', handle_item(fieldarg, content))
        fieldbody = nodes.field_body('', bodynode)
        return nodes.field('', fieldname, fieldbody)
Exemple #34
0
    def make_field(self, types, domain, items, env=None):
        """Copy+Paste of TypedField.make_field() from Sphinx version 1.2.3. The first
        and second nodes.Text() instance are changed in this implementation to
        be ' : ' and '' respectively (instead of ' (' and ')').

        TODO: Ask sphinx devs if there is a better way to support
              this that is less copy+pasty. (thomasvandoren, 2015-03-17)
        """
        def handle_item(fieldarg, content):
            par = nodes.paragraph()
            par += self.make_xref(self.rolename, domain, fieldarg,
                                  nodes.strong)
            if fieldarg in types:
                par += nodes.Text(' : ')
                # NOTE: using .pop() here to prevent a single type node to be
                # inserted twice into the doctree, which leads to
                # inconsistencies later when references are resolved
                fieldtype = types.pop(fieldarg)
                if (len(fieldtype) == 1
                        and isinstance(fieldtype[0], nodes.Text)):
                    typename = u''.join(n.astext() for n in fieldtype)
                    par += self.make_xref(self.typerolename, domain, typename)
                else:
                    par += fieldtype
                par += nodes.Text('')
            par += nodes.Text(' -- ')
            par += content
            return par

        fieldname = nodes.field_name('', self.label)
        if len(items) == 1 and self.can_collapse:
            fieldarg, content = items[0]
            bodynode = handle_item(fieldarg, content)
        else:
            bodynode = self.list_type()
            for fieldarg, content in items:
                bodynode += nodes.list_item('', handle_item(fieldarg, content))
        fieldbody = nodes.field_body('', bodynode)
        return nodes.field('', fieldname, fieldbody)
Exemple #35
0
def patched_make_field(self, types, domain, items):
    # type: (List, unicode, Tuple) -> nodes.field
    def handle_item(fieldarg, content):
        par = nodes.paragraph()
        par += addnodes.literal_strong('', fieldarg)  # Patch: this line added
        # par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
        #                           addnodes.literal_strong))
        if fieldarg in types:
            par += nodes.Text(' (')
            # NOTE: using .pop() here to prevent a single type node to be
            # inserted twice into the doctree, which leads to
            # inconsistencies later when references are resolved
            fieldtype = types.pop(fieldarg)
            if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                typename = u''.join(n.astext() for n in fieldtype)
                typename = typename.replace('int', 'python:int')
                typename = typename.replace('long', 'python:long')
                typename = typename.replace('float', 'python:float')
                typename = typename.replace('type', 'python:type')
                par.extend(
                    self.make_xrefs(self.typerolename, domain, typename,
                                    addnodes.literal_emphasis))
            else:
                par += fieldtype
            par += nodes.Text(')')
        par += nodes.Text(' -- ')
        par += content
        return par

    fieldname = nodes.field_name('', self.label)
    if len(items) == 1 and self.can_collapse:
        fieldarg, content = items[0]
        bodynode = handle_item(fieldarg, content)
    else:
        bodynode = self.list_type()
        for fieldarg, content in items:
            bodynode += nodes.list_item('', handle_item(fieldarg, content))
    fieldbody = nodes.field_body('', bodynode)
    return nodes.field('', fieldname, fieldbody)
Exemple #36
0
 def run(self):
     config = self.state.document.settings.env.config
     model_name = self.arguments[0]
     optfields = self.options.get('fields')
     if not optfields:
         fields = _client.model(model_name).keys()
     else:
         fields = optfields.split(' ')
     l = [
         x for x in fields if x not in
         ['create_uid', 'create_date', 'write_uid', 'write_date']
     ]
     res = _client.execute(model_name,
                           'fields_get',
                           l,
                           context={'lang': config.odoo_lang})
     classes = [config.odoodoc_fieldlistclass]
     if 'class' in self.options:
         classes.extend(self.options['class'])
     return [
         nodes.field_list(
             '',
             *(
                 nodes.field(
                     '',
                     nodes.field_name(text=v['string'] or k),
                     nodes.field_body(
                         '',
                         # keep help formatting around (e.g. newlines for lists)
                         nodes.line_block(
                             '',
                             *(nodes.line(text=line)
                               for line in v['help'].split('\n')))))
                 for k, v in res.iteritems()
                 # only display if there's a help text
                 if v.get('help')),
             classes=classes)
     ]
Exemple #37
0
    def make_field(self,
                   types,     # type: Dict[unicode, List[nodes.Node]]
                   domain,    # type: unicode
                   items,     # type: Tuple
                   env=None,  # type: BuildEnvironment
                   ):
        # type: (...) -> nodes.field
        fieldname = nodes.field_name('', self.label)
        listnode = self.list_type()
        for fieldarg, content in items:
            par = nodes.paragraph()
            par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
                                       addnodes.literal_strong, env=env))
            par += nodes.Text(' -- ')
            par += content
            listnode += nodes.list_item('', par)

        if len(items) == 1 and self.can_collapse:
            fieldbody = nodes.field_body('', listnode[0][0])
            return nodes.field('', fieldname, fieldbody)

        fieldbody = nodes.field_body('', listnode)
        return nodes.field('', fieldname, fieldbody)
Exemple #38
0
    def run(self, reader: LineReader, document: Element) -> bool:
        if reader.lineno != 0:
            return False

        reader.readline()
        field_list = nodes.field_list()
        field_list.source, field_list.line = reader.get_source_and_line()
        for line in reader:
            if self.pattern.match(line):
                break
            elif ':' in line:
                key, value = line.split(':')
                field_name = nodes.field_name('', key.strip())
                field_body = nodes.field_body('', nodes.paragraph('', value.strip()))
                field_list += nodes.field('', field_name, field_body)
            else:
                # Not a frontmatter, rollback
                lines = len(field_list) + 2
                reader.step(-lines)
                return False

        document += field_list
        return True
Exemple #39
0
    def make_field(self, types, domain, item, env=None):
        fieldarg, content = item
        fieldname = nodes.field_name('', self.label)
        if fieldarg:
            fieldname += nodes.Text(' ')
            fieldname.extend(
                self.make_xrefs(self.rolename,
                                domain,
                                fieldarg,
                                nodes.Text,
                                env=env))

        if len(content) == 1 and (isinstance(content[0], nodes.Text) or
                                  (isinstance(content[0], nodes.inline)
                                   and len(content[0]) == 1
                                   and isinstance(content[0][0], nodes.Text))):
            content = self.make_xrefs(self.bodyrolename,
                                      domain,
                                      content[0].astext(),
                                      contnode=content[0],
                                      env=env)
        fieldbody = nodes.field_body('', nodes.paragraph('', '', *content))
        return nodes.field('', fieldname, fieldbody)
Exemple #40
0
    def make_field(self, types, domain, items, env=None):
        fieldname = nodes.field_name('', self.label)
        listnode = self.list_type()
        for fieldarg, content in items:
            par = nodes.paragraph()
            par.extend(
                self.make_xrefs(self.rolename,
                                domain,
                                fieldarg,
                                addnodes.literal_strong,
                                env=env))
            if content and content[0].astext():
                par += nodes.Text(' ')
                par += content
            listnode += nodes.list_item('', par)

            source = env.ref_context['conda:package']
            backrefs = env.domains['conda'].data['backrefs'].setdefault(
                fieldarg, set())
            backrefs.add((env.docname, source))

        fieldbody = nodes.field_body('', listnode)
        return nodes.field('', fieldname, fieldbody)
Exemple #41
0
def patched_make_field(self, types, domain, items, env):
    # type: (list, str, tuple) -> nodes.field
    def handle_item(fieldarg, content):
        par = nodes.paragraph()
        par += addnodes.literal_strong("", fieldarg)  # Patch: this line added
        # par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
        #                           addnodes.literal_strong))
        if fieldarg in types:
            par += nodes.Text(" (")
            # NOTE: using .pop() here to prevent a single type node to be
            # inserted twice into the doctree, which leads to
            # inconsistencies later when references are resolved
            fieldtype = types.pop(fieldarg)
            if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                typename = "".join(n.astext() for n in fieldtype)
                par.extend(
                    self.make_xrefs(
                        self.typerolename, domain, typename, addnodes.literal_emphasis
                    )
                )
            else:
                par += fieldtype
            par += nodes.Text(")")
        par += nodes.Text(" -- ")
        par += content
        return par

    fieldname = nodes.field_name("", self.label)
    if len(items) == 1 and self.can_collapse:
        fieldarg, content = items[0]
        bodynode = handle_item(fieldarg, content)
    else:
        bodynode = self.list_type()
        for fieldarg, content in items:
            bodynode += nodes.list_item("", handle_item(fieldarg, content))
    fieldbody = nodes.field_body("", bodynode)
    return nodes.field("", fieldname, fieldbody)
Exemple #42
0
    def make_content(self, all_members):
        doc = self.item
        content = addnodes.desc_content()

        if doc.exports or doc.dependencies:
            with addto(content, nodes.field_list()) as fields:
                if doc.exports:
                    with addto(fields, nodes.field()) as field:
                        field += nodes.field_name('Exports', 'Exports')
                        with addto(field, nodes.field_body()) as body:
                            ref = doc[
                                'exports']  # warning: not the same as doc.exports
                            label = ref or '<anonymous>'
                            link = addnodes.pending_xref(
                                ref,
                                nodes.paragraph(ref, label),
                                refdomain='js',
                                reftype='any',
                                reftarget=ref,
                            )
                            link['js:module'] = doc.name
                            body += link

                if doc.dependencies:
                    with addto(fields, nodes.field()) as field:
                        self.make_dependencies(field, doc)

        if doc.doc:
            # FIXME: source offset
            self.directive.state.nested_parse(
                to_list(doc.doc, source=doc['sourcefile']), 0, content)

        self.directive.state.nested_parse(self.directive.content, 0, content)

        content += self.document_properties(all_members)

        return content
Exemple #43
0
    def make_field(self, types, domain, item, env=None):
        fieldarg, fieldtype = item

        body = d_nodes.paragraph()
        if fieldarg:
            body.extend(self.make_xrefs(self.rolename, domain, fieldarg,
                                        s_nodes.literal_strong, env=env))

            body += d_nodes.Text('--')

        typename = u''.join(n.astext() for n in fieldtype)
        body.extend(
            self.make_xrefs(self.typerolename, domain, typename,
                            s_nodes.literal_emphasis, env=env))

        fieldname = d_nodes.field_name('', self.label)
        fieldbody = d_nodes.field_body('', body)

        node = d_nodes.field('', fieldname, fieldbody)
        node['eql-name'] = self.name
        node['eql-opname'] = fieldarg
        if typename:
            node['eql-optype'] = typename
        return node
Exemple #44
0
    def make_field(self, types, domain, item, env=None):
        fieldname = d_nodes.field_name('', self.label)

        fieldarg, content = item
        body = d_nodes.paragraph()
        body.extend(self.make_xrefs(self.rolename, domain, fieldarg,
                                    s_nodes.literal_strong, env=env))

        typename = None
        if fieldarg in types:
            body += d_nodes.Text(' (')

            # NOTE: using .pop() here to prevent a single type node to be
            # inserted twice into the doctree, which leads to
            # inconsistencies later when references are resolved
            fieldtype = types.pop(fieldarg)
            if len(fieldtype) == 1 and isinstance(fieldtype[0], d_nodes.Text):
                typename = u''.join(n.astext() for n in fieldtype)
                body.extend(
                    self.make_xrefs(self.typerolename, domain, typename,
                                    s_nodes.literal_emphasis, env=env))
            else:
                body += fieldtype
            body += d_nodes.Text(')')

        body += d_nodes.Text(' -- ')
        body += content

        fieldbody = d_nodes.field_body('', body)

        node = d_nodes.field('', fieldname, fieldbody)
        node['eql-name'] = self.name
        node['eql-paramname'] = fieldarg
        if typename:
            node['eql-paramtype'] = typename
        return node
    def dict_to_fm_field_list(self,
                              data: Dict[str, Any],
                              language_code: str,
                              line: int = 0) -> nodes.field_list:
        """Render each key/val pair as a docutils ``field_node``.

        Bibliographic keys below will be parsed as Markdown,
        all others will be left as literal text.

        The field list should be at the start of the document,
        and will then be converted to a `docinfo` node during the
        `docutils.docutils.transforms.frontmatter.DocInfo` transform (priority 340),
        and bibliographic keys (or their translation) will be converted to nodes::

            {'author': docutils.nodes.author,
            'authors': docutils.nodes.authors,
            'organization': docutils.nodes.organization,
            'address': docutils.nodes.address,
            'contact': docutils.nodes.contact,
            'version': docutils.nodes.version,
            'revision': docutils.nodes.revision,
            'status': docutils.nodes.status,
            'date': docutils.nodes.date,
            'copyright': docutils.nodes.copyright,
            'dedication': docutils.nodes.topic,
            'abstract': docutils.nodes.topic}

        Also, the 'dedication' and 'abstract' will be placed outside the `docinfo`,
        and so will always be shown in the document.

        If using sphinx, this `docinfo` node will later be extracted from the AST,
        by the `DoctreeReadEvent` transform (priority 880),
        calling `MetadataCollector.process_doc`.
        In this case keys and values will be converted to strings and stored in
        `app.env.metadata[app.env.docname]`

        See
        https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
        for docinfo fields used by sphinx.

        """
        field_list = nodes.field_list()

        bibliofields = get_language(language_code).bibliographic_fields
        state_machine = MockStateMachine(self, line)
        state = MockState(self, state_machine, line)

        for key, value in data.items():
            if not isinstance(value, (str, int, float, date, datetime)):
                value = json.dumps(value)
            value = str(value)
            if key in bibliofields:
                para_nodes, _ = state.inline_text(value, line)
                body_children = [nodes.paragraph("", "", *para_nodes)]
            else:
                body_children = [nodes.Text(value, value)]

            field_node = nodes.field()
            field_node.source = value
            field_node += nodes.field_name(key, "", nodes.Text(key, key))
            field_node += nodes.field_body(value, *body_children)
            field_list += field_node

        return field_list
Exemple #46
0
 def make_field(self, name, body):
     if not isinstance(body, nodes.Node):
         body = nodes.paragraph(text=body)
     return nodes.field('', nodes.field_name(text=name),
                        nodes.field_body('', body))
Exemple #47
0
    def make_field(self, types, domain, items, env=None, **kwargs):
        def handle_item(fieldarg, content):
            """Handles translating an item into a node.

            :param str fieldarg: The name of the field.  This is either in the
                format of 'some_field', 'some_field|object', or
                'some_field|objectproperty'.  If there is a `|` character in
                the fieldarg it is treated differently in order to generate
                a sub-list for objects.
            :param list(docutils.nodes.node) content: The content field which
                contains a list of node types to render.
            :returns: A tuple containing the item as a node paragraph and
                a list node if the item is an object, otherwise None.
            """
            # store a copy of the original value for looking up types within
            # this function.
            orig_fieldarg = fieldarg
            # Determine if the field is an object or not.
            is_object = False
            fieldargs = fieldarg.split('|')
            fieldarg = fieldargs[0]
            if len(fieldargs) == 2 and fieldargs[1] == 'object':
                is_object = True

            par = nodes.paragraph()
            par += self.make_xref(self.rolename, domain, fieldarg,
                                  addnodes.literal_strong)
            if orig_fieldarg in types:
                par += nodes.Text(' (')
                # NOTE: using .pop() here to prevent a single type node to be
                # inserted twice into the doctree, which leads to
                # inconsistencies later when references are resolved
                fieldtype = types.pop(orig_fieldarg)
                if len(fieldtype) == 1 and isinstance(fieldtype[0],
                                                      nodes.Text):
                    typename = u''.join(n.astext() for n in fieldtype)
                    par += self.make_xref(self.typerolename, domain, typename,
                                          addnodes.literal_emphasis)
                else:
                    par += fieldtype
                par += nodes.Text(')')
            par += nodes.Text(' -- ')
            # We need to add each child node individually.  If we don't and
            # just do `par += content` the order of the rendered nodes sometimes
            # is generated in an unexpected order.
            for item in content:
                for node in item.children:
                    par += node

            # If the item is an object we need to create a sub-list to show
            # all of the object's properties.
            ul = None
            if is_object:
                ul = self.list_type()
                obj_pos = items.index((orig_fieldarg, content))
                # Loop over all items after the current item and add them to
                # the sub list until we reach the end of the item's properties.
                for obj_prop, content in items[obj_pos + 1:]:
                    fieldargs = obj_prop.split('|')
                    if len(fieldargs
                           ) == 2 and fieldargs[1] == 'objectproperty':
                        # Remove the object property from items so we don't
                        # document it again as we iterate over items outside
                        # of this function.
                        items.remove((obj_prop, content))
                        li, _ = handle_item(obj_prop, content)
                        ul += nodes.list_item('', li)
                    else:
                        break
            return (par, ul)

        fieldname = nodes.field_name('', self.label)
        if len(items) == 1 and self.can_collapse:
            fieldarg, content = items[0]
            bodynode, _ = handle_item(fieldarg, content)
        else:
            bodynode = self.list_type()
            for fieldarg, content in items:
                li, ul = handle_item(fieldarg, content)
                # If the item was an object we will have a sub-list returned
                # that we should add to the list item.
                if ul:
                    li += ul
                bodynode += nodes.list_item('', li)
        fieldbody = nodes.field_body('', bodynode)
        return nodes.field('', fieldname, fieldbody)
Exemple #48
0
 def make_field(self, types, domain, item, env=None):
     fieldarg, content = item
     fieldname = nodes.field_name('', '', nodes.emphasis('', self.label))
     fieldbody = nodes.field_body('')
     return nodes.field('', fieldname, fieldbody)
Exemple #49
0
def process_motor_nodes(app, doctree):
    # Search doctree for Motor's methods and attributes whose docstrings were
    # copied from PyMongo, and fix them up for Motor:
    #   1. Add a 'callback' param (sometimes optional, sometimes required) to
    #      all async methods. If the PyMongo method took no params, we create
    #      a parameter-list from scratch, otherwise we edit PyMongo's list.
    #   2. Remove all version annotations like "New in version 2.0" since
    #      PyMongo's version numbers are meaningless in Motor's docs.
    #   3. Remove "seealso" directives that reference PyMongo's docs.
    #
    # We do this here, rather than by registering a callback to Sphinx's
    # 'autodoc-process-signature' event, because it's way easier to handle the
    # parsed doctree before it's turned into HTML than it is to update the RST.
    for objnode in doctree.traverse(desc):
        if objnode['objtype'] in ('method', 'attribute'):
            signature_node = find_by_path(objnode, [desc_signature])[0]
            name = '.'.join([
                signature_node['module'], signature_node['fullname']])

            assert name.startswith('motor.')
            obj_motor_info = motor_info.get(name)
            if obj_motor_info:
                desc_content_node = find_by_path(objnode, [desc_content])[0]
                if obj_motor_info.get('is_async_method'):
                    try:
                        # Find the parameter list, a bullet_list instance
                        parameters_node = find_by_path(
                            desc_content_node,
                            [field_list, field, field_body, bullet_list])[0]
                    except IndexError:
                        # PyMongo method has no parameters, create an empty
                        # params list
                        parameters_node = bullet_list()
                        parameters_field_list_node = field_list(
                            '',
                            field(
                                '',
                                field_name('', 'Parameters '),
                                field_body('', parameters_node)))

                        desc_content_node.append(parameters_field_list_node)

                    insert_callback(parameters_node)

                    callback_future_text = (
                        "If a callback is passed, returns None, else returns a"
                        " Future.")

                    desc_content_node.append(
                        paragraph('', Text(callback_future_text)))

                if obj_motor_info['is_pymongo_docstring']:
                    # Remove all "versionadded", "versionchanged" and
                    # "deprecated" directives from the docs we imported from
                    # PyMongo
                    version_nodes = find_by_path(
                        desc_content_node, [versionmodified])

                    for version_node in version_nodes:
                        version_node.parent.remove(version_node)

                    # Remove all "seealso" directives that contain :doc:
                    # references from PyMongo's docs
                    seealso_nodes = find_by_path(desc_content_node, [seealso])

                    for seealso_node in seealso_nodes:
                        if 'reftype="doc"' in str(seealso_node):
                            seealso_node.parent.remove(seealso_node)
Exemple #50
0
    def run(self):
        self.cabal_meta = self.get_meta()
        result = super(CabalObject, self).run()

        if self.cabal_meta.since is not None \
           or self.cabal_meta.deprecated is not None:

            #find content part of description
            for item in result:
                if isinstance(item, addnodes.desc):
                    desc = item
                    break
            else:
                return result

            for item in desc:
                if isinstance(item, addnodes.desc_content):
                    contents = item
                    break
            else:
                return result

            # find exsting field list and add to it
            # or create new one
            for item in contents:
                if isinstance(item, nodes.field_list):
                    field_list = item
                    break
            else:
                field_list = nodes.field_list('')
                contents.insert(0, field_list)


            if self.cabal_meta.since is not None:
                #docutils horror
                field = nodes.field('')
                field_name = nodes.field_name('Since', 'Since')
                since = 'Cabal ' + str(self.cabal_meta.since)
                field_body = nodes.field_body(since, nodes.paragraph(since, since))
                field += field_name
                field += field_body
                field_list.insert(0, field)

            if self.cabal_meta.deprecated is not None:
                field = nodes.field('')
                field_name = nodes.field_name('Deprecated', 'Deprecated')
                if isinstance(self.cabal_meta.deprecated, StrictVersion):
                    since = 'Cabal ' + str(self.cabal_meta.deprecated)
                else:
                    since = ''

                field_body = nodes.field_body(since, nodes.paragraph(since, since))
                field += field_name
                field += field_body
                field_list.insert(0, field)

            if self.cabal_meta.removed is not None:
                field = nodes.field('')
                field_name = nodes.field_name('Removed', 'Removed')
                if isinstance(self.cabal_meta.removed, StrictVersion):
                    since = 'Cabal ' + str(self.cabal_meta.removed)
                else:
                    since = ''

                field_body = nodes.field_body(since, nodes.paragraph(since, since))
                field += field_name
                field += field_body
                field_list.insert(0, field)
        return result
    def _run_role(self, role):
        html = self._get_readme_html(os.path.join(role, 'README.md'))
        section = self._section_block(title='Role Documentation',
                                      raw_html=True,
                                      text=html)
        defaults_file = os.path.join(role, 'defaults', 'main.yml')
        if os.path.exists(defaults_file):
            with open(defaults_file) as f:
                role_defaults = DOCYAML.load(f.read())
            section.append(
                self._yaml_section(
                    to_yaml_data=role_defaults,
                    section_title='Role Defaults',
                    section_text='This section highlights all of the defaults'
                    ' and variables set within the "{}"'
                    ' role.'.format(os.path.basename(role))))
        vars_path = os.path.join(role, 'vars')
        if os.path.exists(vars_path):
            for v_file in os.listdir(vars_path):
                vars_file = os.path.join(vars_path, v_file)
                with open(vars_file) as f:
                    vars_values = DOCYAML.load(f.read())
                if vars_values:
                    section.append(
                        self._yaml_section(
                            to_yaml_data=vars_values,
                            section_title='Role Variables: {}'.format(v_file)))

        test_list = nodes.field_list()
        test_section = self._section_block(
            title='Molecule Scenarios',
            text='Molecule is being used to test the "{}" role. The'
            ' following section highlights the drivers in service'
            ' and provides an example playbook showing how the role'
            ' is leveraged.'.format(os.path.basename(role)))
        molecule_path = os.path.join(role, 'molecule')
        if os.path.exists(molecule_path):
            for test in os.listdir(molecule_path):
                molecule_section = self._section_block(
                    title='Scenario: {}'.format(test))
                molecule_file = os.path.join(molecule_path, test,
                                             'molecule.yml')
                if not os.path.exists(molecule_file):
                    continue

                with open(molecule_file) as f:
                    molecule_conf = DOCYAML.load(f.read())

                driver_data = molecule_conf.get('driver')
                if driver_data:
                    molecule_section.append(
                        nodes.field_name(
                            text='Driver: {}'.format(driver_data['name'])))

                    options = driver_data.get('options')
                    if options:
                        molecule_section.append(
                            self._yaml_section(
                                to_yaml_data=options,
                                section_title='Molecule Options'))

                provisioner_data = molecule_conf.get('provisioner')
                if provisioner_data:
                    inventory = provisioner_data.get('inventory')
                    if inventory:
                        molecule_section.append(
                            self._yaml_section(
                                to_yaml_data=inventory,
                                section_title='Molecule Inventory'))

                molecule_playbook_path = os.path.join(molecule_path, test,
                                                      'converge.yml')
                if not os.path.exists(molecule_playbook_path):
                    molecule_playbook_path = os.path.join(
                        molecule_path, test, 'playbook.yml')
                with open(molecule_playbook_path) as f:
                    molecule_playbook = DOCYAML.load(f.read())
                molecule_section.append(
                    self._yaml_section(
                        to_yaml_data=molecule_playbook,
                        section_title='Example {} playbook'.format(test)))
                test_list.append(molecule_section)
            else:
                test_section.append(test_list)
                section.append(test_section)

        self.run_returns.append(section)

        # Document any libraries nested within the role
        library_path = os.path.join(role, 'library')
        if os.path.exists(library_path):
            self.options['documentation'] = True
            self.options['examples'] = True
            for lib in os.listdir(library_path):
                if lib.endswith('.py'):
                    self._run_module(
                        module=self.load_module(
                            filename=os.path.join(library_path, lib)),
                        module_title='Embedded module: {}'.format(lib),
                        example_title='Examples for embedded module')
Exemple #52
0
    def make_field(self,
                   types,
                   domain,
                   items,
                   shapes=None,
                   attrs=None,
                   modname=None,
                   typename=None):
        def handle_item(fieldarg, content):
            par = nodes.paragraph()
            if self.prefix:
                par += self.namefmt(self.prefix, self.prefix)

            par += self.make_xref(self.rolename,
                                  domain,
                                  fieldarg,
                                  self.namefmt,
                                  modname=modname,
                                  typename=typename)
            #par += self.namefmt(fieldarg, fieldarg)

            fieldtype = types.pop(fieldarg, None)
            fieldshape = shapes and shapes.pop(fieldarg, None)
            fieldattrs = attrs and attrs.pop(fieldarg, None)
            if fieldshape:
                shape = parse_shape(fieldshape[0].astext())
                #par += nodes.Text(' %s'%shape)
                add_shape(par, shape, modname=modname)
            if fieldtype or fieldattrs:
                par += nodes.emphasis(' [', ' [')
            if fieldtype:
                if len(fieldtype) == 1 and isinstance(fieldtype[0],
                                                      nodes.Text):
                    thistypename = fieldtype[0].astext()
                    #typename = u''.join(n.astext() for n in fieldtype)
                    par += self.make_xref(self.typerolename,
                                          domain,
                                          thistypename,
                                          modname=modname,
                                          typename=typename)
                else:
                    par += fieldtype
            if fieldattrs:
                if fieldtype: par += nodes.emphasis(',', ',')
                par += fieldattrs
            if fieldtype or fieldattrs:
                par += nodes.emphasis(']', ']')
            if content:
                if fieldarg:
                    par += nodes.Text(' :: ')
                par += content
            return par

        if len(items) == 1 and self.can_collapse:
            fieldarg, content = items[0]
            bodynode = handle_item(fieldarg, content)
        else:
            bodynode = self.list_type()
            for fieldarg, content in items:
                bodynode += nodes.list_item('', handle_item(fieldarg, content))
        label = self.label or ''
        fieldname = nodes.field_name('', label)
        fieldbody = nodes.field_body('', bodynode)
        return nodes.field('', fieldname, fieldbody)
Exemple #53
0
 def make_field(self, name, content):
     fieldname = nodes.field_name('', name)
     fieldbody = nodes.field_body('', nodes.paragraph('', '', content))
     return nodes.field('', fieldname, fieldbody)
    def run(self):
        """
        Main directive entry function, called by docutils upon encountering the
        directive.

        This directive is meant to be quite easily subclassable, so it delegates
        to several additional methods.  What it does:

        * find out if called as a domain-specific directive, set self.domain
        * create a `desc` node to fit all description inside
        * parse standard options, currently `noindex`
        * create an index node if needed as self.indexnode
        * parse all given signatures (as returned by self.get_signatures())
          using self.handle_signature(), which should either return a name
          or raise ValueError
        * add index entries using self.add_target_and_index()
        * parse the content and handle doc fields in it

        This method was copied and adapted from
        sphinx.directive.ObjectDescription.run() (in Sphinx 1.1)

        """
        if ':' in self.name:
            self.domain, self.objtype = self.name.split(':', 1)
        else:
            self.domain, self.objtype = '', self.name
        self.env = self.state.document.settings.env
        self.indexnode = addnodes.index(entries=[])

        node = addnodes.desc()
        node.document = self.state.document
        node['domain'] = self.domain
        # 'desctype' is a backwards compatible attribute
        node['objtype'] = node['desctype'] = self.objtype
        node['noindex'] = noindex = ('noindex' in self.options)

        self.names = []
        signatures = self.get_signatures()
        name = None
        for i, sig in enumerate(signatures):
            # add a signature node for each signature in the current unit
            # and add a reference target for it
            signode = addnodes.desc_signature(sig, '')
            signode['first'] = False
            node.append(signode)
            try:
                # name can also be a tuple, e.g. (classname, objname);
                # this is strictly domain-specific (i.e. no assumptions may
                # be made in this base class)
                name = self.handle_signature(sig, signode)
            except ValueError:
                # signature parsing failed
                signode.clear()
                signode += addnodes.desc_name(sig, sig)
                continue  # we don't want an index entry here
            if not noindex and name is not None and name not in self.names:
                # only add target and index entry if this is the first
                # description of the object with this name in this desc block
                self.names.append(name)
                self.add_target_and_index(name, sig, signode)

        contentnode = addnodes.desc_content()
        node.append(contentnode)
        if self.names:
            # needed for association of version{added,changed} directives
            self.env.temp_data['object'] = self.names[0]
        self.before_content()
        self.state.nested_parse(self.content, self.content_offset, contentnode)
        for child in contentnode:
            if isinstance(child, nodes.field_list):
                child.insert(
                    0,
                    nodes.field(
                        '', nodes.field_name('',
                                             u'param std::string eventName'),
                        nodes.field_body(
                            '', nodes.paragraph('', u'"{0}"'.format(name)))))
                child.append(
                    nodes.field(
                        '',
                        nodes.field_name(
                            '', u'param std::string subscriberIdentifier'),
                        nodes.field_body('', nodes.paragraph('', u''))))

        DocFieldTransformer(self).transform_all(contentnode)
        self.env.temp_data['object'] = None
        self.after_content()
        return [self.indexnode, node]
Exemple #55
0
    def handle_doc_fields(self, node):
        """
        Convert field lists with known keys inside the description content into
        better-looking equivalents.
        """
        # don't traverse, only handle field lists that are immediate children
        for child in node.children:
            if not isinstance(child, nodes.field_list):
                continue
            params = []
            pfield = None
            param_nodes = {}
            param_types = {}
            new_list = nodes.field_list()
            for field in child:
                fname, fbody = field
                try:
                    typ, obj = fname.astext().split(None, 1)
                    typdesc = _(self.doc_fields_with_arg[typ])
                    if _is_only_paragraph(fbody):
                        children = fbody.children[0].children
                    else:
                        children = fbody.children
                    if typdesc == '%param':
                        if not params:
                            # add the field that later gets all the parameters
                            pfield = nodes.field()
                            new_list += pfield
                        dlitem = nodes.list_item()
                        dlpar = nodes.paragraph()
                        dlpar += nodes.emphasis(obj, obj)
                        dlpar += nodes.Text(' -- ', ' -- ')
                        dlpar += children
                        param_nodes[obj] = dlpar
                        dlitem += dlpar
                        params.append(dlitem)
                    elif typdesc == '%type':
                        typenodes = fbody.children
                        if _is_only_paragraph(fbody):
                            typenodes = ([nodes.Text(' (')] +
                                         typenodes[0].children +
                                         [nodes.Text(')')])
                        param_types[obj] = typenodes
                    else:
                        fieldname = typdesc + ' '
                        nfield = nodes.field()
                        nfieldname = nodes.field_name(fieldname, fieldname)
                        nfield += nfieldname
                        node = nfieldname
                        if typ in self.doc_fields_with_linked_arg:
                            node = addnodes.pending_xref(
                                obj,
                                reftype='obj',
                                refcaption=False,
                                reftarget=obj,
                                modname=self.env.currmodule,
                                classname=self.env.currclass)
                            nfieldname += node
                        node += nodes.Text(obj, obj)
                        nfield += nodes.field_body()
                        nfield[1] += fbody.children
                        new_list += nfield
                except (KeyError, ValueError):
                    fnametext = fname.astext()
                    try:
                        typ = _(self.doc_fields_without_arg[fnametext])
                    except KeyError:
                        # at least capitalize the field name
                        typ = fnametext.capitalize()
                    fname[0] = nodes.Text(typ)
                    new_list += field
            if params:
                if len(params) == 1:
                    pfield += nodes.field_name('', _('Parameter'))
                    pfield += nodes.field_body()
                    pfield[1] += params[0][0]
                else:
                    pfield += nodes.field_name('', _('Parameters'))
                    pfield += nodes.field_body()
                    pfield[1] += nodes.bullet_list()
                    pfield[1][0].extend(params)

            for param, type in param_types.iteritems():
                if param in param_nodes:
                    param_nodes[param][1:1] = type
            child.replace_self(new_list)
Exemple #56
0
    def run(self):
        env = self.state.document.settings.env
        txb_name = self.arguments[0]
        txb_id = nodes.make_id(txb_name)

        # First, make a generic desc() node to be the parent.
        node = sphinx.addnodes.desc()
        node.document = self.state.document
        node['objtype'] = 'directive'

        # Next, make a signature node. This creates a permalink and a highlighted background when the link is selected.
        title = sphinx.addnodes.desc_signature(txb_name, '')
        title['ids'].append(txb_name)
        title['ids'].append(txb_id)
        title['names'].append(txb_name)
        title['first'] = False
        title['objtype'] = 'directive'
        self.add_name(title)
        title.set_class('directive-title')

        # Finally, add a desc_name() node to display the name of the
        # configuration variable.
        title += sphinx.addnodes.desc_name(txb_name, txb_name)

        node.append(title)
        if ('class' in self.options):
            title.set_class(self.options.get('class'))

        # This has to be a distinct node before the title. if nested then the browser will scroll forward to just past the title.
        anchor = nodes.target('', '', names=[txb_name])
        # Second (optional) arg is 'msgNode' - no idea what I should pass for that
        # or if it even matters, although I now think it should not be used.
        self.state.document.note_explicit_target(title)
        env.domaindata['txb']['directive'][txb_name] = env.docname

        fl = nodes.field_list()
        if ('keys' in self.options):
            key_field = nodes.field()
            key_field.append(nodes.field_name(text='Secondary Keys'))
            key_value = nodes.field_list()
            key_body = nodes.field_body()
            key_body.append(key_value)
            key_field.append(key_body)
            key_list = self.options['keys'].split('|')
            for key in key_list:
                tag = key
                descr = ''
                if ':' in key:
                    (tag, descr) = key.split(':')
                tag = tag.strip()
                descr = descr.strip()
                key_value.append(self.make_field(tag, descr))
            fl.append(key_field)
        if ('arg' in self.options):
            fl.append(self.make_field('Argument', self.options['arg']))
        if ('value' in self.options):
            fl.append(self.make_field('Value', self.options['value']))

        # Get any contained content
        nn = nodes.compound()
        self.state.nested_parse(self.content, self.content_offset, nn)

        # Create an index node so that Sphinx adds this directive to the index.
        indexnode = sphinx.addnodes.index(entries=[])
        indexnode['entries'].append(
            ('single', _('%s') % txb_name, txb_id, '', ''))

        return [indexnode, node, fl, nn]
    def _run_role(self, role):
        section = self._section_block(
            title='Role Documentation',
            text='Welcome to the "{}" role documentation.'.format(
                os.path.basename(role)))
        defaults_file = os.path.join(role, 'defaults', 'main.yml')
        if os.path.exists(defaults_file):
            with open(defaults_file) as f:
                role_defaults = yaml.safe_load(f.read())
            section.append(
                self._yaml_section(
                    to_yaml_data=role_defaults,
                    section_title='Role Defaults',
                    section_text='This section highlights all of the defaults'
                    ' and variables set within the "{}"'
                    ' role.'.format(os.path.basename(role))))

        vars_path = os.path.join(role, 'vars')
        if os.path.exists(vars_path):
            for v_file in os.listdir(vars_path):
                vars_file = os.path.join(vars_path, v_file)
                with open(vars_file) as f:
                    vars_values = yaml.safe_load(f.read())
                section.append(
                    self._yaml_section(
                        to_yaml_data=vars_values,
                        section_title='Role Variables: {}'.format(v_file)))

        test_list = nodes.field_list()
        test_section = self._section_block(
            title='Molecule Scenarios',
            text='Molecule is being used to test the "{}" role. The'
            ' following section highlights the drivers in service'
            ' and provides an example playbook showing how the role'
            ' is leveraged.'.format(os.path.basename(role)))
        molecule_path = os.path.join(role, 'molecule')
        if os.path.exists(molecule_path):
            for test in os.listdir(molecule_path):
                molecule_section = self._section_block(
                    title='Scenario: {}'.format(test))
                molecule_file = os.path.join(molecule_path, test,
                                             'molecule.yml')
                with open(molecule_file) as f:
                    molecule_conf = yaml.safe_load(f.read())

                driver_data = molecule_conf.get('driver')
                if driver_data:
                    molecule_section.append(
                        nodes.field_name(
                            text='Driver: {}'.format(driver_data['name'])))

                    options = driver_data.get('options')
                    if options:
                        molecule_section.append(
                            self._yaml_section(
                                to_yaml_data=options,
                                section_title='Molecule Options'))

                provisioner_data = molecule_conf.get('provisioner')
                if provisioner_data:
                    inventory = provisioner_data.get('inventory')
                    if inventory:
                        molecule_section.append(
                            self._yaml_section(
                                to_yaml_data=inventory,
                                section_title='Molecule Inventory'))

                molecule_playbook_path = os.path.join(molecule_path, test,
                                                      'playbook.yml')
                with open(molecule_playbook_path) as f:
                    molecule_playbook = yaml.safe_load(f.read())
                molecule_section.append(
                    self._yaml_section(
                        to_yaml_data=molecule_playbook,
                        section_title='Example {} playbook'.format(test)))
                test_list.append(molecule_section)
            else:
                test_section.append(test_list)
                section.append(test_section)

        self.run_returns.append(section)
Exemple #58
0
    def run(self):
        # Tests don't have to have contents now, so check for it but don't assert:
        self.document = self.state_machine.document
        text = []
        if self.content:
            text = '\n'.join(self.content)

        # Create the admonition node, to be populated by `nested_parse`.

        self.name = self.arguments[0]

        if 'test_time' in self.options:
            self.test_time = self.options['test_time']

        # test_procedure name
        #if 'test_procedure' in self.options:
        if 'test_procedure' in self.options:
            self.test_procedure = self.options['test_procedure']
        else:
            self.assert_has_content()
            proc = TestProcedure(self.name + "_procedure")
            self.test_procedure = proc.name
            if 'setup' in self.options:
                proc.setup = self.options['setup']
            else:
                proc.setup = ""
            proc.content = self.content
            self.parsed('test_procedure').append(proc)

        term = nodes.term()
        term += nodes.strong(text=self.arguments[0])

        targetnode = self.make_targetnode()

        deflist = nodes.definition_list()
        test_def = nodes.definition_list_item()
        test_def += term
        defn = nodes.definition()
        test_def += defn
        deflist += test_def

        if 'parameters' in self.options:
            params = self.parse_parameters()

            defn += nodes.paragraph(text="Parameters:")
            for param in params:
                name = param['param']
                field_list = nodes.field_list()
                param_field = nodes.field()
                param_field_name = nodes.field_name()
                param_field_name += nodes.Text(name)
                param_field += param_field_name
                param_field_body = nodes.field_body()
                choices_str = param['choices_str']
                if (len(choices_str) < 50):
                    param_field_body += nodes.paragraph(text=choices_str)
                else:
                    choices = param['choices']
                    param_field_body += nodes.raw('',
                                                  ' \\ \n\n',
                                                  format="latex")
                    for choice in choices:
                        param_field_body += nodes.paragraph(text=choice)
                param_field += param_field_body
                field_list += param_field
                name = self.arguments[0].strip() + "param" + name
                param_target = nodes.target('', '', ids=[nodes.make_id(name)])
                name = nodes.fully_normalize_name(name)
                param_target['names'].append(name)
                self.state_machine.document.note_explicit_target(
                    param_target, param_target)
                defn += param_target
                defn += field_list

        # Parse the directive contents.
        self.state.nested_parse(self.content, self.content_offset, defn)

        option_map = {}
        option_map['configurations'] = 'Valid configurations'
        option_map['setup'] = 'Required setup'
        option_map['test_time'] = 'Test time (min)'
        option_map['priority'] = 'Priority'
        option_map['test_procedure'] = 'Test procedure'
        field_list = self.options_to_field_list(option_map)

        if (field_list != None):
            defn += field_list

        self.parsed('test').append(self)
        return [targetnode, deflist]
Exemple #59
0
def process_motor_nodes(app, doctree):
    # Search doctree for Motor's methods and attributes whose docstrings were
    # copied from PyMongo, and fix them up for Motor:
    #   1. Add a 'callback' param (sometimes optional, sometimes required) to
    #      all Motor Tornado methods. If the PyMongo method took no params, we
    #      create a parameter-list from scratch, otherwise we edit PyMongo's
    #      list.
    #   2. Remove all version annotations like "New in version 2.0" since
    #      PyMongo's version numbers are meaningless in Motor's docs.
    #   3. Remove "seealso" directives that reference PyMongo's docs.
    #
    # We do this here, rather than by registering a callback to Sphinx's
    # 'autodoc-process-signature' event, because it's way easier to handle the
    # parsed doctree before it's turned into HTML than it is to update the RST.
    for objnode in doctree.traverse(desc):
        if objnode['objtype'] in ('method', 'attribute'):
            signature_node = find_by_path(objnode, [desc_signature])[0]
            name = '.'.join([
                signature_node['module'], signature_node['fullname']])

            assert name.startswith('motor.')
            obj_motor_info = motor_info.get(name)
            if obj_motor_info:
                desc_content_node = find_by_path(objnode, [desc_content])[0]
                if (desc_content_node.line is None and
                        obj_motor_info['is_pymongo_docstring']):
                    maybe_warn_about_code_block(name, desc_content_node)

                if obj_motor_info['is_async_method']:
                    # Might be a handwritten RST with "coroutine" already.
                    if not has_coro_annotation(signature_node):
                        coro_annotation = addnodes.desc_annotation(
                            'coroutine ', 'coroutine ',
                            classes=['coro-annotation'])

                        signature_node.insert(0, coro_annotation)

                    if not is_asyncio_api(name):
                        retval = ("If a callback is passed, returns None, else"
                                  " returns a Future.")

                        callback_p = paragraph('', Text(retval))

                        # Find the parameter list.
                        parameters_nodes = find_by_path(
                            desc_content_node, [
                                field_list,
                                field,
                                field_body,
                                (bullet_list, paragraph)])

                        if parameters_nodes:
                            parameters_node = parameters_nodes[0]
                        else:
                            # PyMongo method has no parameters, create an empty
                            # params list
                            parameters_node = bullet_list()
                            parameters_field_list_node = field_list(
                                '',
                                field(
                                    '',
                                    field_name('', 'Parameters '),
                                    field_body('', parameters_node)))
                            desc_content_node.append(parameters_field_list_node)

                        insert_callback(parameters_node)
                        if retval not in str(desc_content_node):
                            desc_content_node.append(callback_p)

                if obj_motor_info['is_pymongo_docstring']:
                    # Remove all "versionadded", "versionchanged" and
                    # "deprecated" directives from the docs we imported from
                    # PyMongo
                    version_nodes = find_by_path(
                        desc_content_node, [versionmodified])

                    for version_node in version_nodes:
                        version_node.parent.remove(version_node)

                    # Remove all "seealso" directives that contain :doc:
                    # references from PyMongo's docs
                    seealso_nodes = find_by_path(desc_content_node, [seealso])

                    for seealso_node in seealso_nodes:
                        if 'reftype="doc"' in str(seealso_node):
                            seealso_node.parent.remove(seealso_node)
def make_field(
		self,
		types: Dict[str, List[nodes.Node]],
		domain: str,
		items: Tuple,
		env: Optional[BuildEnvironment] = None,
		**kwargs,  # To support Sphinx 4.1 and later
		) -> nodes.field:

	def handle_item(fieldarg: str, content: List[nodes.Element]) -> nodes.paragraph:
		par = nodes.paragraph()
		par.extend(
				self.make_xrefs(
						self.rolename,
						domain,
						fieldarg,
						addnodes.literal_strong,
						env=env,
						**kwargs,  # To support Sphinx 4.1 and later
						)
				)

		if fieldarg in types:
			par += nodes.Text(" (")
			# NOTE: using .pop() here to prevent a single type node to be
			# inserted twice into the doctree, which leads to
			# inconsistencies later when references are resolved
			fieldtype = types.pop(fieldarg)

			if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
				typename = fieldtype[0].astext()
				par.extend(
						self.make_xrefs(self.typerolename, domain, typename, addnodes.literal_emphasis, env=env)
						)
			else:
				par += fieldtype

			par += nodes.Text(')')

		if (content and len(content) == 1 and isinstance(content[0], nodes.inline) and not content[0].children):
			return par

		par += nodes.Text(" -- ")
		par += content

		return par

	fieldname = nodes.field_name('', self.label)
	bodynode: nodes.Node

	if len(items) == 1 and self.can_collapse:
		fieldarg, content = items[0]
		bodynode = handle_item(fieldarg, content)
	else:
		bodynode = self.list_type()
		for fieldarg, content in items:
			bodynode += nodes.list_item('', handle_item(fieldarg, content))  # type: ignore

	fieldbody = nodes.field_body('', bodynode)

	return nodes.field('', fieldname, fieldbody)