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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
"""The citation domain."""

from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set, Tuple, cast

from docutils import nodes
from docutils.nodes import Element

from sphinx.addnodes import pending_xref
from sphinx.domains import Domain
from sphinx.locale import __
from sphinx.transforms import SphinxTransform
from sphinx.util import logging
from sphinx.util.nodes import copy_source_info, make_refnode

if TYPE_CHECKING:
    from sphinx.application import Sphinx
    from sphinx.builders import Builder
    from sphinx.environment import BuildEnvironment


logger = logging.getLogger(__name__)


class CitationDomain(Domain):
    """Domain for citations."""

    name = 'citation'
    label = 'citation'

    dangling_warnings = {
        'ref': 'citation not found: %(target)s',
    }

    @property
    def citations(self) -> Dict[str, Tuple[str, str, int]]:
        return self.data.setdefault('citations', {})

    @property
    def citation_refs(self) -> Dict[str, Set[str]]:
        return self.data.setdefault('citation_refs', {})

    def clear_doc(self, docname: str) -> None:
        for key, (fn, _l, _lineno) in list(self.citations.items()):
            if fn == docname:
                del self.citations[key]
        for key, docnames in list(self.citation_refs.items()):
            if docnames == {docname}:
                del self.citation_refs[key]
            elif docname in docnames:
                docnames.remove(docname)

    def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None:
        # XXX duplicates?
        for key, data in otherdata['citations'].items():
            if data[0] in docnames:
                self.citations[key] = data
        for key, data in otherdata['citation_refs'].items():
            citation_refs = self.citation_refs.setdefault(key, set())
            for docname in data:
                if docname in docnames:
                    citation_refs.add(docname)

    def note_citation(self, node: nodes.citation) -> None:
        label = node[0].astext()
        if label in self.citations:
            path = self.env.doc2path(self.citations[label][0])
            logger.warning(__('duplicate citation %s, other instance in %s'), label, path,
                           location=node, type='ref', subtype='citation')
        self.citations[label] = (node['docname'], node['ids'][0], node.line)

    def note_citation_reference(self, node: pending_xref) -> None:
        docnames = self.citation_refs.setdefault(node['reftarget'], set())
        docnames.add(self.env.docname)

    def check_consistency(self) -> None:
        for name, (docname, _labelid, lineno) in self.citations.items():
            if name not in self.citation_refs:
                logger.warning(__('Citation [%s] is not referenced.'), name,
                               type='ref', subtype='citation', location=(docname, lineno))

    def resolve_xref(self, env: "BuildEnvironment", fromdocname: str, builder: "Builder",
                     typ: str, target: str, node: pending_xref, contnode: Element
                     ) -> Optional[Element]:
        docname, labelid, lineno = self.citations.get(target, ('', '', 0))
        if not docname:
            return None

        return make_refnode(builder, fromdocname, docname,
                            labelid, contnode)

    def resolve_any_xref(self, env: "BuildEnvironment", fromdocname: str, builder: "Builder",
                         target: str, node: pending_xref, contnode: Element
                         ) -> List[Tuple[str, Element]]:
        refnode = self.resolve_xref(env, fromdocname, builder, 'ref', target, node, contnode)
        if refnode is None:
            return []
        else:
            return [('ref', refnode)]


class CitationDefinitionTransform(SphinxTransform):
    """Mark citation definition labels as not smartquoted."""
    default_priority = 619

    def apply(self, **kwargs: Any) -> None:
        domain = cast(CitationDomain, self.env.get_domain('citation'))
        for node in self.document.findall(nodes.citation):
            # register citation node to domain
            node['docname'] = self.env.docname
            domain.note_citation(node)

            # mark citation labels as not smartquoted
            label = cast(nodes.label, node[0])
            label['support_smartquotes'] = False


class CitationReferenceTransform(SphinxTransform):
    """
    Replace citation references by pending_xref nodes before the default
    docutils transform tries to resolve them.
    """
    default_priority = 619

    def apply(self, **kwargs: Any) -> None:
        domain = cast(CitationDomain, self.env.get_domain('citation'))
        for node in self.document.findall(nodes.citation_reference):
            target = node.astext()
            ref = pending_xref(target, refdomain='citation', reftype='ref',
                               reftarget=target, refwarn=True,
                               support_smartquotes=False,
                               ids=node["ids"],
                               classes=node.get('classes', []))
            ref += nodes.inline(target, '[%s]' % target)
            copy_source_info(node, ref)
            node.replace_self(ref)

            # register reference node to domain
            domain.note_citation_reference(ref)


def setup(app: "Sphinx") -> Dict[str, Any]:
    app.add_domain(CitationDomain)
    app.add_transform(CitationDefinitionTransform)
    app.add_transform(CitationReferenceTransform)

    return {
        'version': 'builtin',
        'env_version': 1,
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }