| 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} |