Debian Codegraph @

src/repoze/sphinx/autointerface.py

raw
1
2 import sys
3
4 from sphinx.util.docstrings import prepare_docstring
5 from sphinx.domains.python import PyClasslike
6 from sphinx.ext import autodoc
7 from zope.interface import Interface
8 from zope.interface.interface import InterfaceClass
9
10
11 class InterfaceDesc(PyClasslike):
12 def get_index_text(self, modname, name_cls):
13 return '%s (interface in %s)' % (name_cls[0], modname)
14
15
16 class InterfaceDocumenter(autodoc.ClassDocumenter):
17 """
18 Specialized Documenter directive for zope interfaces.
19 """
20 objtype = "interface"
21 # Must be a higher priority than ClassDocumenter
22 member_order = 10
23
24 def __init__(self, *args, **kwargs):
25 super(InterfaceDocumenter, self).__init__(*args, **kwargs)
26 self.options.show_inheritance = True
27
28 @classmethod
29 def can_document_member(cls, member, membername, isattr, parent):
30 return isinstance(member, InterfaceClass)
31
32 def add_directive_header(self, sig):
33 if self.doc_as_attr:
34 self.directivetype = 'attribute'
35 autodoc.Documenter.add_directive_header(self, sig)
36
37 # add inheritance info, if wanted
38 bases = [base for base in self.object.__bases__
39 if base is not Interface]
40 if not self.doc_as_attr and self.options.show_inheritance and bases:
41 self.add_line(u'', '<autodoc>')
42 bases = [u':class:`%s.%s`' % (b.__module__, b.getName())
43 for b in bases]
44 self.add_line(u' Extends: %s' % ', '.join(bases),
45 '<autodoc>')
46
47 def format_args(self):
48 return ""
49
50 def document_members(self, all_members=True):
51 oldindent = self.indent
52 members = list(self.object.namesAndDescriptions())
53
54 if self.options.members is not autodoc.ALL:
55 specified = []
56 for line in (self.options.members or []):
57 specified.extend(line.split())
58 mapping = dict(members)
59 members = [(x, mapping[x]) for x in specified]
60 member_order = (self.options.member_order or
61 self.env.config.autodoc_member_order)
62 if member_order == 'alphabetical':
63 members.sort()
64 if member_order == 'groupwise':
65 # sort by group; relies on stable sort to keep items in the
66 # same group sorted alphabetically
67 members.sort(key=lambda e:
68 getattr(e[1], 'getSignatureString',
69 None) is not None)
70 elif member_order == 'bysource' and self.analyzer:
71 # sort by source order, by virtue of the module analyzer
72 tagorder = self.analyzer.tagorder
73 name = self.object.__name__
74 def keyfunc(entry):
75 return tagorder.get('%s.%s' % (name, entry[0]), len(tagorder))
76 members.sort(key=keyfunc)
77
78 for name, desc in members:
79 self.add_line(u'', '<autointerface>')
80 sig = getattr(desc, 'getSignatureString', None)
81 if sig is None:
82 self.add_line(u'.. attribute:: %s' % name, '<autointerface>')
83 else:
84 self.add_line(u'.. method:: %s%s' % (name, sig()),
85 '<autointerface>')
86 doc = desc.getDoc()
87 if doc:
88 self.add_line(u'', '<autointerface>')
89 self.indent += self.content_indent
90 sourcename = u'docstring of %s.%s' % (self.fullname, name)
91 docstrings = [prepare_docstring(doc)]
92 for i, line in enumerate(self.process_doc(docstrings)):
93 self.add_line(line, sourcename, i)
94 self.add_line(u'', '<autointerface>')
95 self.indent = oldindent
96
97
98 def setup(app):
99 app.add_directive_to_domain('py', 'interface', InterfaceDesc)
100
101 from sphinx.domains import ObjType
102
103 try:
104 domains = app.domains
105 except AttributeError:
106 domains = app.registry.domains
107
108 # Allow the :class: directive to xref interface objects through the search
109 # mechanism, i.e., prefixed with a '.', like :class:`.ITheInterface`
110 # (without this, an exact match is required)
111 class InterfacePythonDomain(domains['py']):
112 pass
113 InterfacePythonDomain.object_types = domains['py'].object_types.copy()
114 InterfacePythonDomain.object_types['interface'] = ObjType( 'interface', 'interface', 'obj', 'class')
115 old_class = InterfacePythonDomain.object_types['class']
116 new_class = ObjType( old_class.lname, *(old_class.roles + ('interface',)), **old_class.attrs )
117 InterfacePythonDomain.object_types['class'] = new_class
118
119 if hasattr(app, 'override_domain'):
120 app.override_domain( InterfacePythonDomain )
121 else:
122 app.add_domain( InterfacePythonDomain, override=True )
123
124 app.add_autodocumenter(InterfaceDocumenter)