/usr/lib/python3/dist-packages/pybtex_docutils.py is in python3-pybtex-docutils 0.2.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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('\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,
}
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
|