This repository has been archived by the owner on Apr 22, 2022. It is now read-only.
/
sphinx_wiring.py
154 lines (130 loc) · 5.17 KB
/
sphinx_wiring.py
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
import inspect
from sphinx.domains.python import PyClasslike, PyXRefRole
from sphinx.ext import autodoc
from sphinx.locale import _
from sphinx.util import force_decode
from sphinx.util.docstrings import prepare_docstring
from wiring.interface import Interface, Method, get_implemented_interfaces
class InterfaceDesc(PyClasslike):
def get_index_text(self, modname, name_cls):
return '{name} (interface in {module})'.format(
name=name_cls[0],
module=modname
)
class InterfaceDocumenter(autodoc.ClassDocumenter):
objtype = 'interface'
member_order = 20
def __init__(self, *args, **kwargs):
super(InterfaceDocumenter, self).__init__(*args, **kwargs)
self.options.show_inheritance = True
def add_directive_header(self, sig):
if self.doc_as_attr:
self.directivetype = 'attribute'
autodoc.Documenter.add_directive_header(self, sig)
bases = [
base for base in self.object.__bases__ if base is not Interface
]
if not self.doc_as_attr and self.options.show_inheritance and bases:
self.add_line(u'', '<autodoc>')
bases = [
u':class:`{module}.{name}`'.format(
module=base.__module__,
name=base.__name__
)
for base in bases
]
self.add_line(
u' Extends: {}'.format(', '.join(bases)),
'<autodoc>'
)
def format_args(self):
return ''
def document_members(self, all_members=True):
oldindent = self.indent
members = list(self.object.attributes.items())
if self.options.members is not autodoc.ALL:
specified = []
for line in (self.options.members or []):
specified.extend(line.split())
members = {
name: value for name, value in members if name in specified
}
member_order = (
self.options.member_order or self.env.config.autodoc_member_order
)
if member_order == 'alphabetical':
members.sort()
if member_order == 'groupwise':
members.sort(key=lambda e: isinstance(e[1], Method))
elif member_order == 'bysource' and self.analyzer:
name = self.object.__name__
def keyfunc(entry):
return self.analyzer.tagorder.get(
'.'.join((name, entry[0])),
len(self.analyzer.tagorder)
)
members.sort(key=keyfunc)
for name, specification in members:
self.add_line(u'', '<autointerface>')
if isinstance(specification, Method):
self.add_line(
u'.. method:: {name}{arguments}'.format(
name=name,
arguments=inspect.formatargspec(
*specification.argument_specification
)
),
'<autointerface>'
)
else:
self.add_line(
u'.. attribute:: {name}'.format(name=name),
'<autointerface>'
)
doc = specification.docstring
if doc:
self.add_line(u'', '<autointerface>')
self.indent += self.content_indent
sourcename = u'docstring of %s.%s' % (self.fullname, name)
docstrings = [prepare_docstring(force_decode(doc, None))]
for i, line in enumerate(self.process_doc(docstrings)):
self.add_line(line, sourcename, i)
self.add_line(u'', '<autointerface>')
self.indent = oldindent
def class_interface_documenter(app, what, name, obj, options, lines):
if what != 'class':
return
if options.show_interfaces:
interfaces = [
u':py:interface:`{name} <{module}.{name}>`'.format(
module=interface.__module__,
name=interface.__name__
)
for interface in get_implemented_interfaces(obj)
]
lines.insert(
0,
_(u'Implements: {}').format(', '.join(interfaces))
)
lines.insert(1, u'')
def method_interface_documenter(app, what, name, obj, options, lines):
if what != 'method':
return
if lines:
return
if not getattr(obj, 'im_class'):
return
interfaces = get_implemented_interfaces(obj.im_class)
for interface in interfaces:
if obj.__name__ in interface.attributes:
docstring = interface.attributes[obj.__name__].docstring
lines.extend(
prepare_docstring(force_decode(docstring, None))
)
def setup(app):
app.add_directive_to_domain('py', 'interface', InterfaceDesc)
app.add_role_to_domain('py', 'interface', PyXRefRole())
app.add_autodocumenter(InterfaceDocumenter)
autodoc.ClassDocumenter.option_spec['show-interfaces'] = lambda arg: True
app.connect('autodoc-process-docstring', class_interface_documenter)
app.connect('autodoc-process-docstring', method_interface_documenter)