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 from sphinx.util import logging
   8
   9 from . import get_doxygen_root
  10 from .xmlutils import format_xml_paragraph
  11
  12 import sys
  13
  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.
  17
  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
  23
  24     option_spec = {
  25         'members': members_option,
  26     }
  27
  28     def __init__(self, directive, name, indent=u'', id=None):
  29         super(DoxygenDocumenter, self).__init__(directive, name, indent)
  30         if id is not None:
  31             self.parse_id(id)
  32
  33     def parse_id(self, id):
  34         return False
  35
  36     def parse_name(self):
  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.
  40         """
  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())
  45
  46         # If we were provided a prototype, that must be an overloaded function. Save it.
  47         self.argsstring = None
  48         if "(" in self.name:
  49             (self.name, self.argsstring) = self.name.split('(', 1)
  50             self.argsstring = "({}".format(self.argsstring)
  51
  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
  57         self.objpath = []
  58
  59         if '::' in self.name:
  60             parts = self.name.split('::')
  61             self.objname = parts[-1]
  62         else:
  63             self.objname = self.name
  64
  65         return True
  66
  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),
  74                       sourcename)
  75
  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*.
  80         """
  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)
  85
  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]
  90
  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)]
  96             if not classes:
  97                 # don't know how to document this member
  98                 continue
  99
 100             # prefer the documenter with the highest priority
 101             classes.sort(key=lambda cls: cls.priority)
 102
 103             documenter = classes[-1](self.directive, mname, indent=self.indent, id=member.get('id'))
 104             memberdocumenters.append((documenter, isattr))
 105
 106         for documenter, isattr in memberdocumenters:
 107             documenter.generate(
 108                 all_members=True, real_modname=self.real_modname,
 109                 check_module=members_check_module and not isattr)
 110
 111         # reset current objects
 112         self.env.temp_data['autodoc:module'] = None
 113         self.env.temp_data['autodoc:class'] = None
 114
 115
 116 class DoxygenClassDocumenter(DoxygenDocumenter):
 117     objtype = 'doxyclass'
 118     directivetype = 'class'
 119     domain = 'cpp'
 120     priority = 100
 121
 122     option_spec = {
 123         'members': members_option,
 124     }
 125
 126     @classmethod
 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.
 133         return False
 134
 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*,
 138         and *self.modname*.
 139
 140         Returns True if successful, False if an error occurred.
 141         """
 142         xpath_query = './/compoundname[text()="%s"]/..' % self.fullname
 143         match = get_doxygen_root().xpath(xpath_query)
 144         if len(match) != 1:
 145             raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried'
 146                                  'the following xpath: "%s"' % (self.fullname, xpath_query))
 147
 148         self.object = match[0]
 149         return True
 150
 151     def format_signature(self):
 152         return ''
 153
 154     def format_name(self):
 155         return self.fullname
 156
 157     def get_doc(self, encoding):
 158         detaileddescription = self.object.find('detaileddescription')
 159         doc = [format_xml_paragraph(detaileddescription)]
 160         return doc
 161
 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"]')
 165
 166         if want_all:
 167             return False, ((m.find('name').text, m) for m in all_members)
 168         else:
 169             if not self.options.members:
 170                 return False, []
 171             else:
 172                 return False, ((m.find('name').text, m) for m in all_members
 173                                if m.find('name').text in self.options.members)
 174
 175     def filter_members(self, members, want_all):
 176         ret = []
 177         for (membername, member) in members:
 178             ret.append((membername, member, False))
 179         return ret
 180
 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))
 185
 186
 187 class DoxygenMethodDocumenter(DoxygenDocumenter):
 188     objtype = 'doxymethod'
 189     directivetype = 'function'
 190     domain = 'cpp'
 191     priority = 100
 192
 193     @classmethod
 194     def can_document_member(cls, member, membername, isattr, parent):
 195         if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'function':
 196             return True
 197         return False
 198
 199     def parse_id(self, id):
 200         xp = './/*[@id="%s"]' % id
 201         match = get_doxygen_root().xpath(xp)
 202         if len(match) > 0:
 203             match = match[0]
 204             self.fullname = match.find('./definition').text.split()[-1]
 205             self.modname = self.fullname
 206             self.objname = match.find('./name').text
 207             self.object = match
 208         return False
 209
 210     def import_object(self):
 211         if ET.iselement(self.object):
 212             # self.object already set from DoxygenDocumenter.parse_name(),
 213             # caused by passing in the `id` of the node instead of just a
 214             # classname or method name
 215             return True
 216
 217         (obj, meth) = self.fullname.rsplit('::', 1)
 218
 219         xpath_query_noparam = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
 220                                '/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(obj, meth)
 221         xpath_query = ""
 222 #        print("fullname {}".format(self.fullname))
 223         if self.argsstring != None:
 224             xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'
 225                            '/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(obj,self.argsstring,meth)
 226         else:
 227             xpath_query = xpath_query_noparam
 228         match = get_doxygen_root().xpath(xpath_query)
 229         if len(match) == 0:
 230             logger = logging.getLogger(__name__)
 231
 232             if self.argsstring != None:
 233                 logger.warning("[autodoxy] WARNING: Could not find method {}::{}{}".format(obj, meth, self.argsstring))
 234                 for cand in get_doxygen_root().xpath(xpath_query_noparam):
 235                     logger.warning("[autodoxy] WARNING:   Existing candidate: {}::{}{}".format(obj, meth, cand.find('argsstring').text))
 236             else:
 237                 logger.warning("[autodoxy] WARNING: could not find method {}::{} in Doxygen files".format(obj, meth))
 238             return False
 239         self.object = match[0]
 240         return True
 241
 242     def get_doc(self, encoding):
 243         detaileddescription = self.object.find('detaileddescription')
 244         doc = [format_xml_paragraph(detaileddescription)]
 245         return doc
 246
 247     def format_name(self):
 248         def text(el):
 249             if el.text is not None:
 250                 return el.text
 251             return ''
 252
 253         def tail(el):
 254             if el.tail is not None:
 255                 return el.tail
 256             return ''
 257
 258         rtype_el = self.object.find('type')
 259         rtype_el_ref = rtype_el.find('ref')
 260         if rtype_el_ref is not None:
 261             rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
 262         else:
 263             rtype = rtype_el.text
 264
 265  #       print("rtype: {}".format(rtype))
 266         signame = (rtype and (rtype + ' ') or '') + self.objname
 267         return self.format_template_name() + signame
 268
 269     def format_template_name(self):
 270         types = [e.text for e in self.object.findall('templateparamlist/param/type')]
 271         if len(types) == 0:
 272             return ''
 273         ret = 'template <%s>' % ','.join(types)
 274 #        print ("template: {}".format(ret))
 275         return ret
 276
 277     def format_signature(self):
 278         args = self.object.find('argsstring').text
 279         return args
 280
 281     def document_members(self, all_members=False):
 282         pass