docs/source/_ext/autodoxy/autodoxy/autodoxy.py

   1 from __future__ import print_function, absolute_import, division
   2
   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
   8 from . import get_doxygen_root
   9 from .xmlutils import format_xml_paragraph
  10
  11
  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.
  15
  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
  21
  22     option_spec = {
  23         'members': members_option,
  24     }
  25
  26     def __init__(self, directive, name, indent=u'', id=None):
  27         super(DoxygenDocumenter, self).__init__(directive, name, indent)
  28         if id is not None:
  29             self.parse_id(id)
  30
  31     def parse_id(self, id):
  32         return False
  33
  34     def parse_name(self):
  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.
  38         """
  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())
  43
  44         # If we were provided a prototype, that must be an overloaded function. Save it.
  45         self.argsstring = None
  46         if "(" in self.name:
  47             (self.name, self.argsstring) = self.name.split('(', 1)
  48             self.argsstring = "({}".format(self.argsstring)
  49
  50         # methods in the superclass sometimes use '.' to join namespace/class
  51         # names with method names, and we don't want that.
  52         self.name = self.name.replace('.', '::')
  53         self.fullname = self.name
  54         self.modname = self.fullname
  55         self.objpath = []
  56
  57         if '::' in self.name:
  58             parts = self.name.split('::')
  59             self.objname = parts[-1]
  60         else:
  61             self.objname = self.name
  62
  63         return True
  64
  65     def add_directive_header(self, sig):
  66         """Add the directive header and options to the generated content."""
  67         domain = getattr(self, 'domain', 'cpp')
  68         directive = getattr(self, 'directivetype', self.objtype)
  69         name = self.format_name()
  70         sourcename = self.get_sourcename()
  71         self.add_line(u'.. %s:%s:: %s%s' % (domain, directive, name, sig),
  72                       sourcename)
  73
  74     def document_members(self, all_members=False):
  75         """Generate reST for member documentation.
  76         If *all_members* is True, do all members, else those given by
  77         *self.options.members*.
  78         """
  79         want_all = all_members or self.options.inherited_members or \
  80             self.options.members is ALL
  81         # find out which members are documentable
  82         members_check_module, members = self.get_object_members(want_all)
  83
  84         # remove members given by exclude-members
  85         if self.options.exclude_members:
  86             members = [(membername, member) for (membername, member) in members
  87                        if membername not in self.options.exclude_members]
  88
  89         # document non-skipped members
  90         memberdocumenters = []
  91         for (mname, member, isattr) in self.filter_members(members, want_all):
  92             classes = [cls for cls in itervalues(AutoDirective._registry)
  93                        if cls.can_document_member(member, mname, isattr, self)]
  94             if not classes:
  95                 # don't know how to document this member
  96                 continue
  97
  98             # prefer the documenter with the highest priority
  99             classes.sort(key=lambda cls: cls.priority)
 100
 101             documenter = classes[-1](self.directive, mname, indent=self.indent, id=member.get('id'))
 102             memberdocumenters.append((documenter, isattr))
 103
 104         for documenter, isattr in memberdocumenters:
 105             documenter.generate(
 106                 all_members=True, real_modname=self.real_modname,
 107                 check_module=members_check_module and not isattr)
 108
 109         # reset current objects
 110         self.env.temp_data['autodoc:module'] = None
 111         self.env.temp_data['autodoc:class'] = None
 112
 113
 114 class DoxygenClassDocumenter(DoxygenDocumenter):
 115     objtype = 'doxyclass'
 116     directivetype = 'class'
 117     domain = 'cpp'
 118     priority = 100
 119
 120     option_spec = {
 121         'members': members_option,
 122     }
 123
 124     @classmethod
 125     def can_document_member(cls, member, membername, isattr, parent):
 126         # this method is only called from Documenter.document_members
 127         # when a higher level documenter (module or namespace) is trying
 128         # to choose the appropriate documenter for each of its lower-level
 129         # members. Currently not implemented since we don't have a higher-level
 130         # doumenter like a DoxygenNamespaceDocumenter.
 131         return False
 132
 133     def import_object(self):
 134         """Import the object and set it as *self.object*.  In the call sequence, this
 135         is executed right after parse_name(), so it can use *self.fullname*, *self.objname*,
 136         and *self.modname*.
 137
 138         Returns True if successful, False if an error occurred.
 139         """
 140         xpath_query = './/compoundname[text()="%s"]/..' % self.fullname
 141         match = get_doxygen_root().xpath(xpath_query)
 142         if len(match) != 1:
 143             raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried'
 144                                  'the following xpath: "%s"' % (self.fullname, xpath_query))
 145
 146         self.object = match[0]
 147         return True
 148
 149     def format_signature(self):
 150         return ''
 151
 152     def format_name(self):
 153         return self.fullname
 154
 155     def get_doc(self, encoding):
 156         detaileddescription = self.object.find('detaileddescription')
 157         doc = [format_xml_paragraph(detaileddescription)]
 158         return doc
 159
 160     def get_object_members(self, want_all):
 161         all_members = self.object.xpath('.//sectiondef[@kind="public-func" '
 162             'or @kind="public-static-func"]/memberdef[@kind="function"]')
 163
 164         if want_all:
 165             return False, ((m.find('name').text, m) for m in all_members)
 166         else:
 167             if not self.options.members:
 168                 return False, []
 169             else:
 170                 return False, ((m.find('name').text, m) for m in all_members
 171                                if m.find('name').text in self.options.members)
 172
 173     def filter_members(self, members, want_all):
 174         ret = []
 175         for (membername, member) in members:
 176             ret.append((membername, member, False))
 177         return ret
 178
 179     def document_members(self, all_members=False):
 180         super(DoxygenClassDocumenter, self).document_members(all_members=all_members)
 181         # Uncomment to view the generated rst for the class.
 182         # print('\n'.join(self.directive.result))
 183
 184
 185 class DoxygenMethodDocumenter(DoxygenDocumenter):
 186     objtype = 'doxymethod'
 187     directivetype = 'function'
 188     domain = 'cpp'
 189     priority = 100
 190
 191     @classmethod
 192     def can_document_member(cls, member, membername, isattr, parent):
 193         if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'function':
 194             return True
 195         return False
 196
 197     def parse_id(self, id):
 198         xp = './/*[@id="%s"]' % id
 199         match = get_doxygen_root().xpath(xp)
 200         if len(match) > 0:
 201             match = match[0]
 202             self.fullname = match.find('./definition').text.split()[-1]
 203             self.modname = self.fullname
 204             self.objname = match.find('./name').text
 205             self.object = match
 206         return False
 207
 208     def import_object(self):
 209         if ET.iselement(self.object):
 210             # self.object already set from DoxygenDocumenter.parse_name(),
 211             # caused by passing in the `id` of the node instead of just a
 212             # classname or method name
 213             return True
 214
 215         xpath_query = ""
 216         print("fullname {}".format(self.fullname))
 217         if self.argsstring != None:
 218             (obj, meth) = self.fullname.rsplit('::', 1)
 219             xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
 220                            '/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(obj,self.argsstring,meth)
 221         else:
 222             xpath_query = ('.//compoundname[text()="%s"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
 223                            '/memberdef[@kind="function"]/name[text()="%s"]/..') % tuple(self.fullname.rsplit('::', 1))
 224         match = get_doxygen_root().xpath(xpath_query)
 225         if len(match) == 0:
 226             raise ExtensionError('[autodoxy] could not find method (modname="%s", objname="%s"). I tried '
 227                                  'the following xpath: "%s"' % (tuple(self.fullname.rsplit('::', 1)) + (xpath_query,)))
 228         self.object = match[0]
 229         return True
 230
 231     def get_doc(self, encoding):
 232         detaileddescription = self.object.find('detaileddescription')
 233         doc = [format_xml_paragraph(detaileddescription)]
 234         return doc
 235
 236     def format_name(self):
 237         def text(el):
 238             if el.text is not None:
 239                 return el.text
 240             return ''
 241
 242         def tail(el):
 243             if el.tail is not None:
 244                 return el.tail
 245             return ''
 246
 247         rtype_el = self.object.find('type')
 248         rtype_el_ref = rtype_el.find('ref')
 249         if rtype_el_ref is not None:
 250             rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
 251         else:
 252             rtype = rtype_el.text
 253
 254  #       print("rtype: {}".format(rtype))
 255         signame = (rtype and (rtype + ' ') or '') + self.objname
 256         return self.format_template_name() + signame
 257
 258     def format_template_name(self):
 259         types = [e.text for e in self.object.findall('templateparamlist/param/type')]
 260         if len(types) == 0:
 261             return ''
 262         ret = 'template <%s>' % ','.join(types)
 263 #        print ("template: {}".format(ret))
 264         return ret
 265
 266     def format_signature(self):
 267         args = self.object.find('argsstring').text
 268         return args
 269
 270     def document_members(self, all_members=False):
 271         pass