Debian Codegraph @

Doc/tools/extensions/pyspecific.py

raw
1 # -*- coding: utf-8 -*-
2 """
3 pyspecific.py
4 ~~~~~~~~~~~~~
5
6 Sphinx extension with Python doc-specific markup.
7
8 :copyright: 2008-2014 by Georg Brandl.
9 :license: Python license.
10 """
11
12 import re
13
14 from sphinx import addnodes
15 from sphinx.domains.python import PyFunction, PyMethod
16
17
18 class PyAwaitableMixin(object):
19 def handle_signature(self, sig, signode):
20 ret = super(PyAwaitableMixin, self).handle_signature(sig, signode)
21 signode.insert(0, addnodes.desc_annotation('awaitable ', 'awaitable '))
22 return ret
23
24
25 class PyAwaitableFunction(PyAwaitableMixin, PyFunction):
26 def run(self):
27 self.name = 'py:function'
28 return PyFunction.run(self)
29
30
31 class PyAwaitableMethod(PyAwaitableMixin, PyMethod):
32 def run(self):
33 self.name = 'py:method'
34 return PyMethod.run(self)
35
36
37 # Support for documenting Opcodes
38
39 opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s*\((.*)\))?')
40
41
42 def parse_opcode_signature(env, sig, signode):
43 """Transform an opcode signature into RST nodes."""
44 m = opcode_sig_re.match(sig)
45 if m is None:
46 raise ValueError
47 opname, arglist = m.groups()
48 signode += addnodes.desc_name(opname, opname)
49 if arglist is not None:
50 paramlist = addnodes.desc_parameterlist()
51 signode += paramlist
52 paramlist += addnodes.desc_parameter(arglist, arglist)
53 return opname.strip()
54
55
56 # Support for documenting pdb commands
57
58 pdbcmd_sig_re = re.compile(r'([a-z()!]+)\s*(.*)')
59
60 # later...
61 # pdbargs_tokens_re = re.compile(r'''[a-zA-Z]+ | # identifiers
62 # [.,:]+ | # punctuation
63 # [\[\]()] | # parens
64 # \s+ # whitespace
65 # ''', re.X)
66
67
68 def parse_pdb_command(env, sig, signode):
69 """Transform a pdb command signature into RST nodes."""
70 m = pdbcmd_sig_re.match(sig)
71 if m is None:
72 raise ValueError
73 name, args = m.groups()
74 fullname = name.replace('(', '').replace(')', '')
75 signode += addnodes.desc_name(name, name)
76 if args:
77 signode += addnodes.desc_addname(' '+args, ' '+args)
78 return fullname
79
80
81 def parse_monitoring_event(env, sig, signode):
82 """Transform a monitoring event signature into RST nodes."""
83 signode += addnodes.desc_addname('sys.monitoring.events.', 'sys.monitoring.events.')
84 signode += addnodes.desc_name(sig, sig)
85 return sig
86
87
88 def patch_pairindextypes(app, _env) -> None:
89 """Remove all entries from ``pairindextypes`` before writing POT files.
90
91 We want to run this just before writing output files, as the check to
92 circumvent is in ``I18nBuilder.write_doc()``.
93 As such, we link this to ``env-check-consistency``, even though it has
94 nothing to do with the environment consistency check.
95 """
96 if app.builder.name != 'gettext':
97 return
98
99 # allow translating deprecated index entries
100 try:
101 from sphinx.domains.python import pairindextypes
102 except ImportError:
103 pass
104 else:
105 # Sphinx checks if a 'pair' type entry on an index directive is one of
106 # the Sphinx-translated pairindextypes values. As we intend to move
107 # away from this, we need Sphinx to believe that these values don't
108 # exist, by deleting them when using the gettext builder.
109 pairindextypes.clear()
110
111
112 def setup(app):
113 app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature)
114 app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command)
115 app.add_object_type('monitoring-event', 'monitoring-event', '%s (monitoring event)', parse_monitoring_event)
116 app.add_directive_to_domain('py', 'awaitablefunction', PyAwaitableFunction)
117 app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
118 app.connect('env-check-consistency', patch_pairindextypes)
119 return {'version': '1.0', 'parallel_read_safe': True}