How to use docutils - 10 common examples

def _create_notes_paragraph(self, notes):
        """Constructs a paragraph which represents the implementation notes

        The paragraph consists of text and clickable URL nodes if links were
        given in the notes.
        """
        para = nodes.paragraph()
        para.append(nodes.strong(text="Notes: "))
        # links could start with http:// or https://
        link_idxs = [m.start() for m in re.finditer('https?://', notes)]
        start_idx = 0
        for link_idx in link_idxs:
            # assume the notes start with text (could be empty)
            para.append(nodes.inline(text=notes[start_idx:link_idx]))
            # create a URL node until the next text or the end of the notes
            link_end_idx = notes.find(" ", link_idx)
            if link_end_idx == -1:
                # In case the notes end with a link without a blank
                link_end_idx = len(notes)
            uri = notes[link_idx:link_end_idx + 1]
            para.append(nodes.reference("", uri, refuri=uri))
            start_idx = link_end_idx + 1

        # get all text after the last link (could be empty) or all of the
        # text if no link was given
        para.append(nodes.inline(text=notes[start_idx:]))
        return para

def dashed_issues_appear_as_unlinked_issues(self):
        node = self._generate('1.0.2', _issue('bug', '-'))
        assert not isinstance(node[0][2], reference)

def fake_node(domain, type, target, content, **attrs):
    contnode = nodes.emphasis(content, content)
    node = addnodes.pending_xref('')
    node['reftarget'] = target
    node['reftype'] = type
    node['refdomain'] = domain
    node.attributes.update(attrs)
    node += contnode
    return node, contnode

self.assertEqual(' and ', paragraph[2])
        self.assertIsInstance(paragraph[3], nodes.literal)
        self.assertEqual('code', paragraph[3].astext())
        self.assertIsInstance(paragraph[4], nodes.Text)
        self.assertEqual(' world', paragraph[4])

        items = doc[0][2]
        self.assertIsInstance(items, nodes.bullet_list)
        self.assertEqual(7, len(items))

        # backticks: `e=f()` or ``e=f("`")``
        backticks = items[0][0]
        self.assertIsInstance(backticks, nodes.paragraph)
        self.assertEqual(4, len(backticks))
        self.assertEqual('backticks: ', backticks[0])
        self.assertIsInstance(backticks[1], nodes.literal)
        self.assertEqual('e=f()', backticks[1][0])
        self.assertIsInstance(backticks[2], nodes.Text)
        self.assertEqual(' or ', backticks[2])
        self.assertIsInstance(backticks[3], nodes.literal)
        self.assertEqual('e=f("`")', backticks[3][0])

        # escapes: \*hello world*
        escapes = items[1][0]
        self.assertIsInstance(escapes, nodes.paragraph)
        self.assertEqual(1, len(escapes))
        self.assertIsInstance(escapes[0], nodes.Text)
        self.assertEqual('escapes: *hello world*', escapes[0])

        # strong-em: ***strongem*** or ***em*strong**
        strongem = items[2][0]
        self.assertIsInstance(strongem, nodes.paragraph)

text = utils.unescape(text)
    if typ == 'menuselection':
        text = text.replace('-->', u'\u2192') # Here is the patch

    spans = _amp_re.split(text)  

    node = nodes.literal(rawtext=rawtext)
    for i, span in enumerate(spans):
        span = span.replace('&&', '&')
        if i == 0:
            if len(span) > 0:
                textnode = nodes.Text(span)
                node += textnode
            continue
        accel_node = nodes.inline()
        letter_node = nodes.Text(span[0])
        accel_node += letter_node
        accel_node['classes'].append('accelerator')
        node += accel_node
        textnode = nodes.Text(span[1:])
        node += textnode

    node['classes'].append(typ)
    return [node], []

option_spec = {}
            has_content = True
            def run(self):
                self.assert_has_content()
                args = shlex.split(self.content[0].encode('ascii'))
                text = subprocess.Popen(args,stdout=subprocess.PIPE).communicate()[0]
                return [docutils.nodes.literal_block(text=text)]
        rst.directives.register_directive('shell-block', ShellCommandDirective)

        # doxygen links using breathe
        parser_factory = breathe.DoxygenParserFactory()
        matcher_factory = breathe.ItemMatcherFactory()
        item_finder_factory_creator = breathe.DoxygenItemFinderFactoryCreator(parser_factory, matcher_factory)
        index_parser = breathe.DoxygenIndexParser()
        finder_factory = breathe.FinderFactory(index_parser, item_finder_factory_creator)
        node_factory = breathe.NodeFactory(docutils.nodes,sphinx.addnodes)
        renderer_factory_creator = breathe.DoxygenToRstRendererFactoryCreator(node_factory, parser_factory)
        builder_factory = breathe.BuilderFactory(breathe.RstBuilder, renderer_factory_creator)
        project_info_factory = breathe.ProjectInfoFactory()
        directive_factory = breathe.DoxygenDirectiveFactory(builder_factory, finder_factory, matcher_factory, project_info_factory)
        project_info_factory.update({'openrave':os.path.join(languagecode, 'xml')},'openrave')
        rst.directives.register_directive("doxygenindex", directive_factory.create_index_directive_container())
        rst.directives.register_directive("doxygenfunction", directive_factory.create_function_directive_container())
        rst.directives.register_directive("doxygenstruct", directive_factory.create_struct_directive_container())
        rst.directives.register_directive("doxygenenum",directive_factory.create_enum_directive_container())
        rst.directives.register_directive("doxygentypedef",directive_factory.create_typedef_directive_container())
        rst.directives.register_directive("doxygenclass",directive_factory.create_class_directive_container())

        rst.languages.get_language('ja')

        for source in glob('*.txt'):
            dest = os.path.splitext(source)[0] + '.html'

""" Try and create a reference to a type on MSDN """
    in_msdn = False
    if name in MSDN_VALUE_TYPES:
        name = MSDN_VALUE_TYPES[name]
        in_msdn = True
    if name.startswith('System.'):
        in_msdn = True
    if in_msdn:
        link = name.split('<')[0]
        link = MSDN_LINK_MAP.get(link, link.lower())
        url = ''
        if link.startswith('https://'):
            url = link
        else:
            url = 'https://docs.microsoft.com/en-us/dotnet/api/' + link
        node = nodes.reference(name, shorten_type(name))
        node['refuri'] = url
        node['reftitle'] = name
        return node
    return None

spans = _amp_re.split(text)  

    node = nodes.literal(rawtext=rawtext)
    for i, span in enumerate(spans):
        span = span.replace('&&', '&')
        if i == 0:
            if len(span) > 0:
                textnode = nodes.Text(span)
                node += textnode
            continue
        accel_node = nodes.inline()
        letter_node = nodes.Text(span[0])
        accel_node += letter_node
        accel_node['classes'].append('accelerator')
        node += accel_node
        textnode = nodes.Text(span[1:])
        node += textnode

    node['classes'].append(typ)
    return [node], []

prefix, target_name = target_name[0], target_name[1:]
                if prefix == '.':
                    target_alias = target_name[1:]
                elif prefix == '~':
                    target_alias = target_name.split('.')[-1]
            if target_alias is None:
                target_alias = target_name
            ref_node = addnodes.pending_xref(
                '',
                refdomain=domain,
                refexplicit=False,
                reftype=rolename,
                reftarget=target_alias,
                refspecific=True,
            )
            ref_node += nodes.Text(target_name, target_name)
            if field_node is None:
                field_node = nodes.inline()
                field_node += ref_node
            else:
                inner_node = field_node
                field_node = nodes.inline()
                field_node += [
                    ref_node,
                    nodes.Text('<', '<'),
                    inner_node,
                    nodes.Text('>', '>'),
                ]

        return innernode('', '', field_node)

content = []
        nwarnings = 0

        para = nodes.paragraph()
        sorted_items = sorted(error_cache.items())
        para += nodes.Text("There are {} warnings".format(len(sorted_items)))
        content.append(para)

        for key, value in sorted_items:

            docname, lineno = key.split(":")
            lineno = int(lineno)
            cgatreportwarning, warningclass = value

            para = nodes.paragraph()

            filename = env.doc2path(docname, base=None)

            nwarnings += 1
            location_str = '%s:%d ' % (filename, lineno)

            try:
                description_str = warningclass
            except KeyError:
                description_str = "unknown"

            # Create a reference
            newnode = nodes.reference('', '')
            innernode = nodes.emphasis(_(location_str), _(location_str))
            newnode['refdocname'] = docname