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