File: sphinx_paramlinks.py

package info (click to toggle)
renderdoc 1.24%2Bdfsg-1%2Bdeb12u1
  • links: PTS, VCS
  • area: main
  • in suites: bookworm
  • size: 105,156 kB
  • sloc: cpp: 759,405; ansic: 309,460; python: 26,606; xml: 22,599; java: 11,365; cs: 7,181; makefile: 6,707; yacc: 5,682; ruby: 4,648; perl: 3,461; sh: 2,354; php: 2,119; lisp: 1,835; javascript: 1,524; tcl: 1,068; ml: 747
file content (288 lines) | stat: -rw-r--r-- 10,571 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
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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
#!coding: utf-8
import re
from docutils import nodes
from docutils.transforms import Transform
import os
from sphinx.util.osutil import copyfile
from sphinx.util.console import bold
from sphinx.domains.python import PyXRefRole
from sphinx.domains.python import PythonDomain
from distutils.version import LooseVersion
from sphinx import __version__
# the searchindex.js system relies upon the object types
# in the PythonDomain to create search entries
from sphinx.domains import ObjType
from sphinx.util import logging

try:
    from sphinx.domains.python import ObjectEntry
except:
    from collections import namedtuple
    ObjectEntry = namedtuple('ObjectEntry', ['docname', 'node_id', 'objtype'])

PythonDomain.object_types['parameter'] = ObjType('parameter', 'param')

if 'getLogger' in dir(logging):
    LOG = logging.getLogger(__name__)
else:
    LOG = None


def get_indexentries(app):
    try:
        return app.env.get_domain('index').data['entries']
    except:
        pass
    return app.env.indexentries


def _is_html(app):
    return app.builder.name in ('html', 'readthedocs')


def _tempdata(app):
    if '_sphinx_paramlinks_index' in get_indexentries(app):
        idx = get_indexentries(app)['_sphinx_paramlinks_index']
    else:
        get_indexentries(app)['_sphinx_paramlinks_index'] = idx = {}
    return idx


def autodoc_process_docstring(app, what, name, obj, options, lines):
    # locate :param: lines within docstrings.  augment the parameter
    # name with that of the parent object name plus a token we can
    # spot later.  Also put an index entry in a temporary collection.

    idx = _tempdata(app)

    docname = app.env.temp_data['docname']
    if docname in idx:
        doc_idx = idx[docname]
    else:
        idx[docname] = doc_idx = []

    def _cvt_param(name, line):
        if name.endswith(".__init__"):
            # kill off __init__ if present, the links are always
            # off the class
            name = name[0:-9]

        def cvt(m):
            modifier, objname, paramname = m.group(1) or '', name, m.group(2)
            refname = _refname_from_paramname(paramname, strip_markup=True)
            item = ('single', '%s (%s parameter)' % (refname, objname),
                    '%s.params.%s' % (objname, refname), '')
            if LooseVersion(__version__) >= LooseVersion('1.4.0'):
                item += (None,)
            doc_idx.append(item)
            return ":param %s_sphinx_paramlinks_%s.%s:" % (
                modifier, objname, paramname)
        
        def secondary_cvt(m):
            modifier, objname, paramname = m.group(1) or '', name, m.group(2)
            return ":type %s_sphinx_paramlinks_%s.%s:" % (
                modifier, objname, paramname)
        
        line = re.sub(r'^:param ([^:]+? )?([^:]+?):', cvt, line)
        line = re.sub(r'^:type ([^:]+? )?([^:]+?):', secondary_cvt, line)
        return line

    if what in ('function', 'method', 'class'):
        lines[:] = [_cvt_param(name, line) for line in lines]


def _refname_from_paramname(paramname, strip_markup=False):
    literal_match = re.match(r'^``(.+?)``$', paramname)
    if literal_match:
        paramname = literal_match.group(1)
    refname = paramname
    eq_match = re.match(r'(.+?)=.+$', refname)
    if eq_match:
        refname = eq_match.group(1)
    if strip_markup:
        refname = re.sub(r'\\', '', refname)
    return refname


class LinkParams(Transform):
    # apply references targets and optional references
    # to nodes that contain our target text.
    default_priority = 210

    def apply(self):
        is_html = _is_html(self.document.settings.env.app)

        # seach <strong> nodes, which will include the titles for
        # those :param: directives, looking for our special token.
        # then fix up the text within the node.
        for ref in self.document.traverse(nodes.strong):
            text = ref.astext()
            if text.startswith("_sphinx_paramlinks_"):
                components = re.match(r'_sphinx_paramlinks_(.+)\.(.+)$', text)
                location, paramname = components.group(1, 2)
                refname = _refname_from_paramname(paramname)

                refid = "%s.params.%s" % (location, refname)
                ref.parent.insert(
                    0,
                    nodes.target('', '', ids=[refid])
                )
                del ref[0]

                ref.insert(0, nodes.Text(paramname, paramname))

                if is_html:
                    # add the "p" thing only if we're the HTML builder.

                    # using a real ΒΆ, surprising, right?
                    # http://docutils.sourceforge.net/FAQ.html#how-can-i-represent-esoteric-characters-e-g-character-entities-in-a-document

                    # "For example, say you want an em-dash (XML
                    # character entity &mdash;, Unicode character
                    # U+2014) in your document: use a real em-dash.
                    # Insert concrete characters (e.g. type a real em-
                    # dash) into your input file, using whatever
                    # encoding suits your application, and tell
                    # Docutils the input encoding. Docutils uses
                    # Unicode internally, so the em-dash character is
                    # a real em-dash internally."   OK !

                    for pos, node in enumerate(ref.parent.children):
                        # try to figure out where the node with the
                        # paramname is. thought this was simple, but
                        # readthedocs proving..it's not.
                        # TODO: need to take into account a type name
                        # with the parens.
                        if isinstance(node, nodes.TextElement) and \
                                node.astext() == paramname:
                            break
                    else:
                        return

                    ref.parent.insert(
                        pos + 1,
                        nodes.reference(
                            '', '',
                            nodes.Text(u"#", u"#"),
                            refid=refid,
                            # paramlink is our own CSS class, headerlink
                            # is theirs.  Trying to get everything we can for
                            # existing symbols...
                            classes=['paramlink', 'headerlink']
                        )
                    )


def lookup_params(app, env, node, contnode):
    # here, we catch the "pending xref" nodes that we created with
    # the "paramref" role we added.   The resolve_xref() routine
    # knows nothing about this node type so it never finds anything;
    # the Sphinx BuildEnvironment then gives us one more chance to do a lookup
    # here.

    if node['reftype'] != 'paramref':
        return None

    target = node['reftarget']

    tokens = target.split(".")
    resolve_target = ".".join(tokens[0:-1])
    paramname = tokens[-1]

    # emulate the approach within
    # sphinx.environment.BuildEnvironment.resolve_references
    try:
        domain = env.domains[node['refdomain']]  # hint: this will be 'py'
    except KeyError:
        return None

    # BuildEnvironment doesn't pass us "fromdocname" here as the
    # fallback, oh well
    refdoc = node.get('refdoc', None)

    # we call the same "resolve_xref" that BuildEnvironment just tried
    # to call for us, but we load the call with information we know
    # it can find, e.g. the "object" role (or we could use :meth:/:func:)
    # along with the classname/methodname/funcname minus the parameter
    # part.

    for search in ["meth", "class", "func"]:
        newnode = domain.resolve_xref(
            env, refdoc, app.builder,
            search, resolve_target, node, contnode)
        if newnode is not None:
            break

    if newnode is not None:
        # assuming we found it, tack the paramname back onto to the final
        # URI.
        if 'refuri' in newnode:
            newnode['refuri'] += ".params." + paramname
        elif 'refid' in newnode:
            newnode['refid'] += ".params." + paramname
    return newnode


def add_stylesheet(app):
    if 'add_css_file' in dir(app):
        app.add_css_file('sphinx_paramlinks.css')
    else:
        app.add_stylesheet('sphinx_paramlinks.css')


def copy_stylesheet(app, exception):
    logger = LOG
    if logger is None:
        logger = app
    logger.info(
            bold('The name of the builder is: %s' % app.builder.name), nonl=True)

    if not _is_html(app) or exception:
        return

    logger.info(bold('Copying sphinx_paramlinks stylesheet... '), nonl=True)

    source = os.path.abspath(os.path.dirname(__file__))

    # the '_static' directory name is hardcoded in
    # sphinx.builders.html.StandaloneHTMLBuilder.copy_static_files.
    # would be nice if Sphinx could improve the API here so that we just
    # give it the path to a .css file and it does the right thing.
    dest = os.path.join(app.builder.outdir, '_static', 'sphinx_paramlinks.css')
    copyfile(os.path.join(source, "sphinx_paramlinks.css"), dest)

    logger.info('done')


def build_index(app, doctree):
    entries = _tempdata(app)

    for docname in entries:
        doc_entries = entries[docname]
        get_indexentries(app)[docname].extend(doc_entries)

        for entry in doc_entries:
            sing, desc, ref, extra = entry[:4]
            if LooseVersion(__version__) >= LooseVersion('4.0.0'):
                app.env.domains['py'].data['objects'][ref] = ObjectEntry(docname, ref, 'parameter', False)
            elif LooseVersion(__version__) >= LooseVersion('3.0.0'):
                app.env.domains['py'].data['objects'][ref] = ObjectEntry(docname, ref, 'parameter')
            else:
                app.env.domains['py'].data['objects'][ref] = (docname, 'parameter')

    get_indexentries(app).pop('_sphinx_paramlinks_index')


def setup(app):
    app.add_transform(LinkParams)

    # PyXRefRole is what the sphinx Python domain uses to set up
    # role nodes like "meth", "func", etc.  It produces a "pending xref"
    # sphinx node along with contextual information.
    app.add_role_to_domain("py", "paramref", PyXRefRole())

    app.connect('autodoc-process-docstring', autodoc_process_docstring)
    app.connect('builder-inited', add_stylesheet)
    app.connect('build-finished', copy_stylesheet)
    app.connect('missing-reference', lookup_params)
    app.connect('doctree-read', build_index)