# Source code for pybtex_docutils

    """
    API
    ~~~

    The backend renders :class:`pybtex.richtext.Text` instances
    into a list of :class:`docutils.nodes.Node` instances.
    For typical use cases, all you need to care about are the methods
    :meth:`Backend.paragraph`,
    :meth:`Backend.citation`, and
    :meth:`Backend.citation_reference`
    which are to be called on *formatted* entries,
    as in the :ref:`minimal example <minimal-example>`.

    Unless you are subclassing :class:`Backend` to create a new backend,
    you should normally not import the :mod:`pybtex_docutils` module directly.
    Instead, use pybtex's plugin system to get the :class:`Backend` class,
    as in the :ref:`minimal example <minimal-example>`.

    .. autoclass:: Backend
       :show-inheritance:
       :members: RenderType, paragraph, citation, citation_reference,
                 footnote, footnote_reference
    """

    import docutils.nodes
    import itertools

    from pybtex.backends import BaseBackend
    from typing import TYPE_CHECKING, List, Type

    if TYPE_CHECKING:
        from pybtex.style import FormattedEntry

    class Backend(BaseBackend):
        name = 'docutils'

        symbols = {
            'ndash': [docutils.nodes.Text('\u2013', '\u2013')],
            'newblock': [docutils.nodes.Text(' ', ' ')],
            'nbsp': [docutils.nodes.Text('\u00a0', '\u00a0')],
        }
        tags = {
            'emph': docutils.nodes.emphasis,  # note: deprecated
            'em': docutils.nodes.emphasis,
            'strong': docutils.nodes.strong,
            'i': docutils.nodes.emphasis,
            'b': docutils.nodes.strong,
            'tt': docutils.nodes.literal,
            'sup': docutils.nodes.superscript,
            'sub': docutils.nodes.subscript,
        }

        RenderType: Type[List[docutils.nodes.Node]] = list

        # for compatibility only
        def format_text(self, text: str) -> List[docutils.nodes.Node]:
            return self.format_str(text)

        def format_str(self, str_: str) -> List[docutils.nodes.Node]:
            return [docutils.nodes.Text(str_, str_)]

        def format_tag(self, tag_name: str, text: List[docutils.nodes.Node]
                       ) -> List[docutils.nodes.Node]:
            if tag_name in self.tags:
                tag = self.tags[tag_name]
                return [tag('', '', *text)]
            else:
                return text

        def format_href(self, url: str, text: List[docutils.nodes.Node]
                        ) -> List[docutils.nodes.Node]:
            node = docutils.nodes.reference('', '', *text, refuri=url)
            return [node]

        def write_entry(self, key: str, label: str, text: str) -> None:
            raise NotImplementedError("use Backend.citation() instead")

        def render_sequence(self, rendered_list: List[List[docutils.nodes.Node]]
                            ) -> List[docutils.nodes.Node]:
            return list(itertools.chain(*rendered_list))

        def paragraph(self, entry: "FormattedEntry") -> docutils.nodes.paragraph:
            """Return a docutils.nodes.paragraph
            containing the rendered text for *entry* (without label).

            .. versionadded:: 0.2.0
            """
            return docutils.nodes.paragraph('', '', *entry.text.render(self))

        def citation(self, entry: "FormattedEntry",
                     document: docutils.nodes.document, use_key_as_label=True
                     ) -> docutils.nodes.citation:
            """Return citation node, with key as name, label as first
            child, and paragraph with entry text as second child. The citation is
            expected to be inserted into *document* prior to any docutils
            transforms.
            """
            # see docutils.parsers.rst.states.Body.citation()
            if use_key_as_label:
                label = entry.key
            else:
                label = entry.label
            name = docutils.nodes.fully_normalize_name(entry.key)
            citation = docutils.nodes.citation()
            citation['names'].append(name)
            citation += docutils.nodes.label('', label)
            citation += self.paragraph(entry)
            document.note_citation(citation)
            document.note_explicit_target(citation, citation)
            return citation

        def citation_reference(
                self, entry: "FormattedEntry",
                document: docutils.nodes.document, use_key_as_label=True
                ) -> docutils.nodes.citation_reference:
            """Return citation_reference node to the given citation. The
            citation_reference is expected to be inserted into *document*
            prior to any docutils transforms.
            """
            # see docutils.parsers.rst.states.Body.footnote_reference()
            if use_key_as_label:
                label = entry.key
            else:
                label = entry.label
            refname = docutils.nodes.fully_normalize_name(entry.key)
            refnode = docutils.nodes.citation_reference(
                '[%s]_' % label, refname=refname)
            refnode += docutils.nodes.Text(label)
            document.note_citation_ref(refnode)
            return refnode

        def footnote(self, entry: "FormattedEntry",
                     document: docutils.nodes.document) -> docutils.nodes.footnote:
            """Return footnote node, with key as name, and paragraph with
            entry text as child. The footnote is expected to be
            inserted into *document* prior to any docutils transforms.

            .. versionadded:: 0.2.2
            """
            # see docutils.parsers.rst.states.Body.footnote()
            name = docutils.nodes.fully_normalize_name(entry.key)
            footnote = docutils.nodes.footnote(auto=1)
            footnote['names'].append(name)
            footnote += self.paragraph(entry)
            document.note_autofootnote(footnote)
            document.note_explicit_target(footnote, footnote)
            return footnote

        def footnote_reference(self, entry: "FormattedEntry",
                               document: docutils.nodes.document
                               ) -> docutils.nodes.footnote_reference:
            """Return footnote_reference node to the given citation. The
            footnote_reference is expected to be inserted into *document*
            prior to any docutils transforms.

            .. versionadded:: 0.2.2
            """
            # see docutils.parsers.rst.states.Body.footnote_reference()
            refname = docutils.nodes.fully_normalize_name(entry.key)
            refnode = docutils.nodes.footnote_reference(
                '[#%s]_' % entry.key, refname=refname, auto=1)
            document.note_autofootnote_ref(refnode)
            document.note_footnote_ref(refnode)
            return refnode