1 from __future__ import print_function, absolute_import, division
3 from six import itervalues
4 from lxml import etree as ET
5 from sphinx.ext.autodoc import Documenter, AutoDirective, members_option, ALL
6 from sphinx.errors import ExtensionError
8 from . import get_doxygen_root
9 from .xmlutils import format_xml_paragraph
12 class DoxygenDocumenter(Documenter):
13 # Variables to store the names of the object being documented. modname and fullname are redundant,
14 # and objpath is always the empty list. This is inelegant, but we need to work with the superclass.
16 fullname = None # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName""
17 modname = None # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName""
18 objname = None # example: "NonbondedForce" or "methodName"
19 objpath = [] # always the empty list
20 object = None # the xml node for the object
23 'members': members_option,
26 def __init__(self, directive, name, indent=u'', id=None):
27 super(DoxygenDocumenter, self).__init__(directive, name, indent)
31 def parse_id(self, id):
35 """Determine what module to import and what attribute to document.
36 Returns True and sets *self.modname*, *self.objname*, *self.fullname*,
37 if parsing and resolving was successful.
39 # To view the context and order in which all of these methods get called,
40 # See, Documenter.generate(). That's the main "entry point" that first
41 # calls parse_name(), follwed by import_object(), format_signature(),
42 # add_directive_header(), and then add_content() (which calls get_doc())
44 # methods in the superclass sometimes use '.' to join namespace/class
45 # names with method names, and we don't want that.
46 self.name = self.name.replace('.', '::')
47 self.fullname = self.name
48 self.modname = self.fullname
52 parts = self.name.split('::')
53 self.objname = parts[-1]
55 self.objname = self.name
59 def add_directive_header(self, sig):
60 """Add the directive header and options to the generated content."""
61 domain = getattr(self, 'domain', 'cpp')
62 directive = getattr(self, 'directivetype', self.objtype)
63 name = self.format_name()
64 sourcename = self.get_sourcename()
65 self.add_line(u'.. %s:%s:: %s%s' % (domain, directive, name, sig),
68 def document_members(self, all_members=False):
69 """Generate reST for member documentation.
70 If *all_members* is True, do all members, else those given by
71 *self.options.members*.
73 want_all = all_members or self.options.inherited_members or \
74 self.options.members is ALL
75 # find out which members are documentable
76 members_check_module, members = self.get_object_members(want_all)
78 # remove members given by exclude-members
79 if self.options.exclude_members:
80 members = [(membername, member) for (membername, member) in members
81 if membername not in self.options.exclude_members]
83 # document non-skipped members
84 memberdocumenters = []
85 for (mname, member, isattr) in self.filter_members(members, want_all):
86 classes = [cls for cls in itervalues(AutoDirective._registry)
87 if cls.can_document_member(member, mname, isattr, self)]
89 # don't know how to document this member
92 # prefer the documenter with the highest priority
93 classes.sort(key=lambda cls: cls.priority)
95 documenter = classes[-1](self.directive, mname, indent=self.indent, id=member.get('id'))
96 memberdocumenters.append((documenter, isattr))
98 for documenter, isattr in memberdocumenters:
100 all_members=True, real_modname=self.real_modname,
101 check_module=members_check_module and not isattr)
103 # reset current objects
104 self.env.temp_data['autodoc:module'] = None
105 self.env.temp_data['autodoc:class'] = None
108 class DoxygenClassDocumenter(DoxygenDocumenter):
109 objtype = 'doxyclass'
110 directivetype = 'class'
115 'members': members_option,
119 def can_document_member(cls, member, membername, isattr, parent):
120 # this method is only called from Documenter.document_members
121 # when a higher level documenter (module or namespace) is trying
122 # to choose the appropriate documenter for each of its lower-level
123 # members. Currently not implemented since we don't have a higher-level
124 # doumenter like a DoxygenNamespaceDocumenter.
127 def import_object(self):
128 """Import the object and set it as *self.object*. In the call sequence, this
129 is executed right after parse_name(), so it can use *self.fullname*, *self.objname*,
132 Returns True if successful, False if an error occurred.
134 xpath_query = './/compoundname[text()="%s"]/..' % self.fullname
135 match = get_doxygen_root().xpath(xpath_query)
137 raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried'
138 'the following xpath: "%s"' % (self.fullname, xpath_query))
140 self.object = match[0]
143 def format_signaure(self):
146 def format_name(self):
149 def get_doc(self, encoding):
150 detaileddescription = self.object.find('detaileddescription')
151 doc = [format_xml_paragraph(detaileddescription)]
154 def get_object_members(self, want_all):
155 all_members = self.object.xpath('.//sectiondef[@kind="public-func" '
156 'or @kind="public-static-func"]/memberdef[@kind="function"]')
159 return False, ((m.find('name').text, m) for m in all_members)
161 if not self.options.members:
164 return False, ((m.find('name').text, m) for m in all_members
165 if m.find('name').text in self.options.members)
167 def filter_members(self, members, want_all):
169 for (membername, member) in members:
170 ret.append((membername, member, False))
173 def document_members(self, all_members=False):
174 super(DoxygenClassDocumenter, self).document_members(all_members=all_members)
175 # Uncomment to view the generated rst for the class.
176 # print('\n'.join(self.directive.result))
179 class DoxygenMethodDocumenter(DoxygenDocumenter):
180 objtype = 'doxymethod'
181 directivetype = 'function'
186 def can_document_member(cls, member, membername, isattr, parent):
187 if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'function':
191 def parse_id(self, id):
192 xp = './/*[@id="%s"]' % id
193 match = get_doxygen_root().xpath(xp)
196 self.fullname = match.find('./definition').text.split()[-1]
197 self.modname = self.fullname
198 self.objname = match.find('./name').text
202 def import_object(self):
203 if ET.iselement(self.object):
204 # self.object already set from DoxygenDocumenter.parse_name(),
205 # caused by passing in the `id` of the node instead of just a
206 # classname or method name
209 xpath_query = ('.//compoundname[text()="%s"]/../sectiondef[@kind="public-func"]'
210 '/memberdef[@kind="function"]/name[text()="%s"]/..') % tuple(self.fullname.rsplit('::', 1))
211 match = get_doxygen_root().xpath(xpath_query)
213 raise ExtensionError('[autodoxy] could not find method (modname="%s", objname="%s"). I tried '
214 'the following xpath: "%s"' % (tuple(self.fullname.rsplit('::', 1)) + (xpath_query,)))
215 self.object = match[0]
218 def get_doc(self, encoding):
219 detaileddescription = self.object.find('detaileddescription')
220 doc = [format_xml_paragraph(detaileddescription)]
223 def format_name(self):
225 if el.text is not None:
230 if el.tail is not None:
234 rtype_el = self.object.find('type')
235 rtype_el_ref = rtype_el.find('ref')
236 if rtype_el_ref is not None:
237 rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
239 rtype = rtype_el.text
241 signame = (rtype and (rtype + ' ') or '') + self.objname
242 return self.format_template_name() + signame
244 def format_template_name(self):
245 types = [e.text for e in self.object.findall('templateparamlist/param/type')]
248 return 'template <%s>\n' % ','.join(types)
250 def format_signature(self):
251 args = self.object.find('argsstring').text
254 def document_members(self, all_members=False):