Python docutils.parsers.rst.directives 模块，register_directive() 实例源码

def parse_rst(text: str) -> str:
    """Parse reStructuredText into a tree of nodes."""
    directives.register_directive("linotype", LinotypeDirective)

    option_parser = OptionParser(components=(Parser,))
    settings = option_parser.get_default_values()
    parser = Parser()
    document = new_document("test", settings)
    parser.parse(text, document)
    return document.pformat()

def setup(app):
    """
    Setup function that makes this module a Sphinx extension.

    See http://www.sphinx-doc.org/en/stable/extdev/appapi.html#sphinx.application.Sphinx.add_config_value
    """  # noqa
    # Wee want to override the directives:
    # - 'graph' from sphinx.ext.graphviz extension.
    # - 'uml' from sphinxcontrib.plantuml
    # But Sphinx warns of the override, causing failure if warnings are set
    # to fail documentation build. So, we go down and use docutils registering
    # directly instead.

    # app.add_directive('uml', UmlDirective)
    # app.add_directive('graph', GraphDirective)
    # app.add_directive('diagram', DiagramDirective)

    from docutils.parsers.rst import directives
    directives.register_directive('uml', UmlDirective)
    directives.register_directive('graph', GraphDirective)
    directives.register_directive('diagram', DiagramDirective)

    # Register the config value to allow to set plantweb defaults in conf.py
    app.add_config_value('plantweb_defaults', {}, 'env')

    # Register Plantweb defaults setter
    # Note: The str() is because:
    #       - In Python 2.7, Sphinx expects a str, not unicode.
    #       - In Python 3.4, Sphinx expects a str, not bytes.
    app.connect(str('builder-inited'), builder_inited_handler)

def fix_rst_pep(input_lines, outfile, inpath, pepnum):

    class XXXDirective(rst.Directive):
        has_content = True
        def run(self):
            # Raise an error if the directive does not have contents.
            self.assert_has_content()
            text = '\n'.join(self.content)
            # Create the admonition node, to be populated by `nested_parse`.
            admonition_node = nodes.admonition(rawsource=text)
            # Parse the directive contents.
            self.state.nested_parse(self.content, self.content_offset,
                                    admonition_node)
            title = nodes.title('', 'XXX')
            admonition_node.insert(0, title)
            return [admonition_node]
    directives.register_directive('xxx', XXXDirective)

    handle, template_file_name = tempfile.mkstemp(text=True)
    try:
        orig_template_name = pep_html.Writer.default_template_path
        with open(orig_template_name) as inf, open(handle, 'w') as outf:
            content = inf.read()
            content = content.replace('%(pepnum)s.txt', '%(pepnum)s.rst')
            content = content.replace("%(pepindex)s/", "%(pepindex)s")
            outf.write(content)

        output = core.publish_string(
            source=''.join(input_lines),
            source_path=inpath,
            destination_path=outfile.name,
            reader=Reader(),
            parser_name='restructuredtext',
            writer=Writer(pepnum),
            settings=None,
            # Allow Docutils traceback if there's an exception:
            settings_overrides={
                'traceback': 1,
                'template': template_file_name,
            })
        outfile.write(output.decode('utf-8'))
    finally:
        os.unlink(template_file_name)