File: pybtex_docutils.py

package info (click to toggle)
pybtex-docutils 0.2.1-1.1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 248 kB
  • sloc: python: 314; makefile: 145
file content (124 lines) | stat: -rw-r--r-- 4,254 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
"""
API
~~~

The backend renders :class:`pybtex.richtext.Text` instances
into a list of :class:`docutils.nodes.Text`
and :class:`docutils.nodes.inline` instances (or subclasses of these).
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>`.

Note that you should not import the :mod:`pybtex_docutils` module directly.
Instead, use pybtex's plugin system to get the :class:`Backend` class,
again,
as in the :ref:`minimal example <minimal-example>`.

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

import docutils.nodes
import itertools

from pybtex.backends import BaseBackend
import pybtex.richtext
import six


class Backend(BaseBackend):
    name = 'docutils'

    symbols = {
        'ndash': [docutils.nodes.Text(u'\u2013', u'\u2013')],
        'newblock': [docutils.nodes.Text(u' ', u' ')],
        'nbsp': [docutils.nodes.Text(u'\u00a0', u'\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,
    }
    RenderType = list

    # for compatibility only
    def format_text(self, text):
        return self.format_str(text)

    def format_str(self, str_):
        assert isinstance(str_, six.string_types)
        return [docutils.nodes.Text(str_, str_)]

    def format_tag(self, tag_name, text):
        assert isinstance(tag_name, six.string_types)
        assert isinstance(text, self.RenderType)
        if tag_name in self.tags:
            tag = self.tags[tag_name]
            return [tag('', '', *text)]
        else:
            return text

    def format_href(self, url, text):
        assert isinstance(url, six.string_types)
        assert isinstance(text, self.RenderType)
        node = docutils.nodes.reference('', '', *text, refuri=url)
        return [node]

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

    def render_sequence(self, rendered_list):
        return list(itertools.chain(*rendered_list))

    def paragraph(self, entry):
        """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, document, use_key_as_label=True):
        """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)
        text = entry.text.render(self)
        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, document, use_key_as_label=True):
        """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