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
7 from sphinx.util import logging
9 from . import get_doxygen_root
10 from .xmlutils import format_xml_paragraph
14 class DoxygenDocumenter(Documenter):
15 # Variables to store the names of the object being documented. modname and fullname are redundant,
16 # and objpath is always the empty list. This is inelegant, but we need to work with the superclass.
18 fullname = None # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName""
19 modname = None # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName""
20 objname = None # example: "NonbondedForce" or "methodName"
21 objpath = [] # always the empty list
22 object = None # the xml node for the object
25 'members': members_option,
28 def __init__(self, directive, name, indent=u'', id=None):
29 super(DoxygenDocumenter, self).__init__(directive, name, indent)
33 def parse_id(self, id):
37 """Determine what module to import and what attribute to document.
38 Returns True and sets *self.modname*, *self.objname*, *self.fullname*,
39 if parsing and resolving was successful.
41 # To view the context and order in which all of these methods get called,
42 # See, Documenter.generate(). That's the main "entry point" that first
43 # calls parse_name(), follwed by import_object(), format_signature(),
44 # add_directive_header(), and then add_content() (which calls get_doc())
46 # If we were provided a prototype, that must be an overloaded function. Save it.
47 self.argsstring = None
49 (self.name, self.argsstring) = self.name.split('(', 1)
50 self.argsstring = "({}".format(self.argsstring)
52 # methods in the superclass sometimes use '.' to join namespace/class
53 # names with method names, and we don't want that.
54 self.name = self.name.replace('.', '::')
55 self.fullname = self.name
56 self.modname = self.fullname
60 parts = self.name.split('::')
61 self.objname = parts[-1]
63 self.objname = self.name
67 def add_directive_header(self, sig):
68 """Add the directive header and options to the generated content."""
69 domain = getattr(self, 'domain', 'cpp')
70 directive = getattr(self, 'directivetype', self.objtype)
71 name = self.format_name()
72 sourcename = self.get_sourcename()
73 self.add_line(u'.. %s:%s:: %s%s' % (domain, directive, name, sig),
76 def document_members(self, all_members=False):
77 """Generate reST for member documentation.
78 If *all_members* is True, do all members, else those given by
79 *self.options.members*.
81 want_all = all_members or self.options.inherited_members or \
82 self.options.members is ALL
83 # find out which members are documentable
84 members_check_module, members = self.get_object_members(want_all)
86 # remove members given by exclude-members
87 if self.options.exclude_members:
88 members = [(membername, member) for (membername, member) in members
89 if membername not in self.options.exclude_members]
91 # document non-skipped members
92 memberdocumenters = []
93 for (mname, member, isattr) in self.filter_members(members, want_all):
94 classes = [cls for cls in itervalues(AutoDirective._registry)
95 if cls.can_document_member(member, mname, isattr, self)]
97 # don't know how to document this member
100 # prefer the documenter with the highest priority
101 classes.sort(key=lambda cls: cls.priority)
103 documenter = classes[-1](self.directive, mname, indent=self.indent, id=member.get('id'))
104 memberdocumenters.append((documenter, isattr))
106 for documenter, isattr in memberdocumenters:
108 all_members=True, real_modname=self.real_modname,
109 check_module=members_check_module and not isattr)
111 # reset current objects
112 self.env.temp_data['autodoc:module'] = None
113 self.env.temp_data['autodoc:class'] = None
116 class DoxygenClassDocumenter(DoxygenDocumenter):
117 objtype = 'doxyclass'
118 directivetype = 'class'
123 'members': members_option,
127 def can_document_member(cls, member, membername, isattr, parent):
128 # this method is only called from Documenter.document_members
129 # when a higher level documenter (module or namespace) is trying
130 # to choose the appropriate documenter for each of its lower-level
131 # members. Currently not implemented since we don't have a higher-level
132 # doumenter like a DoxygenNamespaceDocumenter.
135 def import_object(self):
136 """Import the object and set it as *self.object*. In the call sequence, this
137 is executed right after parse_name(), so it can use *self.fullname*, *self.objname*,
140 Returns True if successful, False if an error occurred.
142 xpath_query = './/compoundname[text()="%s"]/..' % self.fullname
143 match = get_doxygen_root().xpath(xpath_query)
145 raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried'
146 'the following xpath: "%s"' % (self.fullname, xpath_query))
148 self.object = match[0]
151 def format_signature(self):
154 def format_name(self):
157 def get_doc(self, encoding):
158 detaileddescription = self.object.find('detaileddescription')
159 doc = [format_xml_paragraph(detaileddescription)]
162 def get_object_members(self, want_all):
163 all_members = self.object.xpath('.//sectiondef[@kind="public-func" '
164 'or @kind="public-static-func"]/memberdef[@kind="function"]')
167 return False, ((m.find('name').text, m) for m in all_members)
169 if not self.options.members:
172 return False, ((m.find('name').text, m) for m in all_members
173 if m.find('name').text in self.options.members)
175 def filter_members(self, members, want_all):
177 for (membername, member) in members:
178 ret.append((membername, member, False))
181 def document_members(self, all_members=False):
182 super(DoxygenClassDocumenter, self).document_members(all_members=all_members)
183 # Uncomment to view the generated rst for the class.
184 # print('\n'.join(self.directive.result))
186 class DoxygenMethodDocumenter(DoxygenDocumenter):
187 objtype = 'doxymethod'
188 directivetype = 'function'
193 def can_document_member(cls, member, membername, isattr, parent):
194 if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'function':
198 def parse_id(self, id):
199 xp = './/*[@id="%s"]' % id
200 match = get_doxygen_root().xpath(xp)
203 self.fullname = match.find('./definition').text.split()[-1]
204 self.modname = self.fullname
205 self.objname = match.find('./name').text
209 def import_object(self):
210 if ET.iselement(self.object):
211 # self.object already set from DoxygenDocumenter.parse_name(),
212 # caused by passing in the `id` of the node instead of just a
213 # classname or method name
216 (obj, meth) = self.fullname.rsplit('::', 1)
218 xpath_query_noparam = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
219 '/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(obj, meth)
221 # print("fullname {}".format(self.fullname))
222 if self.argsstring != None:
223 xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
224 '/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(obj,self.argsstring,meth)
226 xpath_query = xpath_query_noparam
227 match = get_doxygen_root().xpath(xpath_query)
229 logger = logging.getLogger(__name__)
231 if self.argsstring != None:
232 candidates = get_doxygen_root().xpath(xpath_query_noparam)
233 if len(candidates) == 1:
234 logger.warning("[autodoxy] Using method '{}::{}{}' instead of '{}::{}{}'. You may want to drop your specification of the signature, or to fix it."
235 .format(obj, meth, candidates[0].find('argsstring').text, obj, meth, self.argsstring))
236 self.object = candidates[0]
238 logger.warning("[autodoxy] WARNING: Could not find method {}::{}{}".format(obj, meth, self.argsstring))
239 for cand in candidates:
240 logger.warning("[autodoxy] WARNING: Existing candidate: {}::{}{}".format(obj, meth, cand.find('argsstring').text))
242 logger.warning("[autodoxy] WARNING: could not find method {}::{} in Doxygen files".format(obj, meth))
244 self.object = match[0]
247 def get_doc(self, encoding):
248 detaileddescription = self.object.find('detaileddescription')
249 doc = [format_xml_paragraph(detaileddescription)]
252 def format_name(self):
254 if el.text is not None:
259 if el.tail is not None:
263 rtype_el = self.object.find('type')
264 rtype_el_ref = rtype_el.find('ref')
265 if rtype_el_ref is not None:
266 rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
268 rtype = rtype_el.text
270 # print("rtype: {}".format(rtype))
271 signame = (rtype and (rtype + ' ') or '') + self.objname
272 return self.format_template_name() + signame
274 def format_template_name(self):
275 types = [e.text for e in self.object.findall('templateparamlist/param/type')]
278 ret = 'template <%s>' % ','.join(types)
279 # print ("template: {}".format(ret))
282 def format_signature(self):
283 args = self.object.find('argsstring').text
286 def document_members(self, all_members=False):
289 class DoxygenVariableDocumenter(DoxygenDocumenter):
291 directivetype = 'var'
296 def can_document_member(cls, member, membername, isattr, parent):
297 if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'variable':
301 def import_object(self):
302 if ET.iselement(self.object):
303 # self.object already set from DoxygenDocumenter.parse_name(),
304 # caused by passing in the `id` of the node instead of just a
305 # classname or method name
308 (obj, var) = self.fullname.rsplit('::', 1)
310 xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-attrib" or @kind="public-static-attrib"]'
311 '/memberdef[@kind="variable"]/name[text()="{:s}"]/..').format(obj, var)
312 # print("fullname {}".format(self.fullname))
313 match = get_doxygen_root().xpath(xpath_query)
315 logger = logging.getLogger(__name__)
317 logger.warning("[autodoxy] WARNING: could not find variable {}::{} in Doxygen files".format(obj, var))
319 self.object = match[0]
322 def parse_id(self, id):
323 xp = './/*[@id="%s"]' % id
324 match = get_doxygen_root().xpath(xp)
327 self.fullname = match.find('./definition').text.split()[-1]
328 self.modname = self.fullname
329 self.objname = match.find('./name').text
333 def format_name(self):
335 if el.text is not None:
340 if el.tail is not None:
344 rtype_el = self.object.find('type')
345 rtype_el_ref = rtype_el.find('ref')
346 if rtype_el_ref is not None:
347 rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
349 rtype = rtype_el.text
351 # print("rtype: {}".format(rtype))
352 signame = (rtype and (rtype + ' ') or '') + self.objname
353 return self.format_template_name() + signame
355 def get_doc(self, encoding):
356 detaileddescription = self.object.find('detaileddescription')
357 doc = [format_xml_paragraph(detaileddescription)]
360 def format_template_name(self):
361 types = [e.text for e in self.object.findall('templateparamlist/param/type')]
364 ret = 'template <%s>' % ','.join(types)
365 # print ("template: {}".format(ret))
368 def document_members(self, all_members=False):