docs/source/_ext/autodoxy.py

   1 """
   2 This is autodoxy, a sphinx extension providing autodoc-like directives
   3 that are feed with Doxygen files.
   4
   5 It is highly inspired from the autodoc_doxygen sphinx extension, but
   6 adapted to my own needs in SimGrid.
   7 https://github.com/rmcgibbo/sphinxcontrib-autodoc_doxygen
   8
   9 Licence: MIT
  10 Copyright (c) 2015 Robert T. McGibbon
  11 Copyright (c) 2019 Martin Quinson
  12 """
  13 from __future__ import print_function, absolute_import, division
  14
  15 import os.path
  16 import re
  17 import sys
  18
  19 from six import itervalues
  20 from lxml import etree as ET
  21 from sphinx.ext.autodoc import Documenter, AutoDirective, members_option, ALL
  22 from sphinx.errors import ExtensionError
  23 from sphinx.util import logging
  24
  25
  26 ##########################################################################
  27 # XML utils
  28 ##########################################################################
  29 def format_xml_paragraph(xmlnode):
  30     """Format an Doxygen XML segment (principally a detaileddescription)
  31     as a paragraph for inclusion in the rst document
  32
  33     Parameters
  34     ----------
  35     xmlnode
  36
  37     Returns
  38     -------
  39     lines
  40         A list of lines.
  41     """
  42     return [l.rstrip() for l in _DoxygenXmlParagraphFormatter().generic_visit(xmlnode).lines]
  43
  44
  45 class _DoxygenXmlParagraphFormatter(object):
  46     # This class follows the model of the stdlib's ast.NodeVisitor for tree traversal
  47     # where you dispatch on the element type to a different method for each node
  48     # during the traverse.
  49
  50     # It's supposed to handle paragraphs, references, preformatted text (code blocks), and lists.
  51
  52     def __init__(self):
  53         self.lines = ['']
  54         self.continue_line = False
  55
  56     def visit(self, node):
  57         method = 'visit_' + node.tag
  58         visitor = getattr(self, method, self.generic_visit)
  59         return visitor(node)
  60
  61     def generic_visit(self, node):
  62         for child in node.getchildren():
  63             self.visit(child)
  64         return self
  65
  66     def visit_ref(self, node):
  67         ref = get_doxygen_root().findall('.//*[@id="%s"]' % node.get('refid'))
  68         if ref:
  69             ref = ref[0]
  70             if ref.tag == 'memberdef':
  71                 parent = ref.xpath('./ancestor::compounddef/compoundname')[0].text
  72                 name = ref.find('./name').text
  73                 real_name = parent + '::' + name
  74             elif ref.tag in ('compounddef', 'enumvalue'):
  75                 name_node = ref.find('./name')
  76                 real_name = name_node.text if name_node is not None else ''
  77             else:
  78                 raise NotImplementedError(ref.tag)
  79         else:
  80             real_name = None
  81
  82         val = [':cpp:any:`', node.text]
  83         if real_name:
  84             val.extend((' <', real_name, '>`'))
  85         else:
  86             val.append('`')
  87         if node.tail is not None:
  88             val.append(node.tail)
  89
  90         self.lines[-1] += ''.join(val)
  91
  92     def visit_para(self, node):
  93         if node.text is not None:
  94             if self.continue_line:
  95                 self.lines[-1] += node.text
  96             else:
  97                 self.lines.append(node.text)
  98         self.generic_visit(node)
  99         self.lines.append('')
 100         self.continue_line = False
 101
 102     def visit_verbatim(self, node):
 103         if node.text is not None:
 104             # remove the leading ' *' of any lines
 105             lines = [re.sub('^\s*\*','', l) for l in node.text.split('\n')]
 106             # Merge each paragraph together
 107             text = re.sub("\n\n", "PaRaGrraphSplit", '\n'.join(lines))
 108             text = re.sub('\n', '', text)
 109             lines = text.split('PaRaGrraphSplit')
 110
 111             # merge content to the built doc
 112             if self.continue_line:
 113                 self.lines[-1] += lines[0]
 114                 lines = lines[1:]
 115             for l in lines:
 116                 self.lines.append('')
 117                 self.lines.append(l)
 118         self.generic_visit(node)
 119         self.lines.append('')
 120         self.continue_line = False
 121
 122     def visit_parametername(self, node):
 123         if 'direction' in node.attrib:
 124             direction = '[%s] ' % node.get('direction')
 125         else:
 126             direction = ''
 127
 128         self.lines.append('**%s** -- %s' % (
 129             node.text, direction))
 130         self.continue_line = True
 131
 132     def visit_parameterlist(self, node):
 133         lines = [l for l in type(self)().generic_visit(node).lines if l != '']
 134         self.lines.extend([':parameters:', ''] + ['* %s' % l for l in lines] + [''])
 135
 136     def visit_simplesect(self, node):
 137         if node.get('kind') == 'return':
 138             self.lines.append(':returns: ')
 139             self.continue_line = True
 140         self.generic_visit(node)
 141
 142     def visit_listitem(self, node):
 143         self.lines.append('   - ')
 144         self.continue_line = True
 145         self.generic_visit(node)
 146
 147     def visit_preformatted(self, node):
 148         segment = [node.text if node.text is not None else '']
 149         for n in node.getchildren():
 150             segment.append(n.text)
 151             if n.tail is not None:
 152                 segment.append(n.tail)
 153
 154         lines = ''.join(segment).split('\n')
 155         self.lines.extend(('.. code-block:: C++', ''))
 156         self.lines.extend(['  ' + l for l in lines])
 157
 158     def visit_computeroutput(self, node):
 159         c = node.find('preformatted')
 160         if c is not None:
 161             return self.visit_preformatted(c)
 162         return self.visit_preformatted(node)
 163
 164     def visit_xrefsect(self, node):
 165         if node.find('xreftitle').text == 'Deprecated':
 166             sublines = type(self)().generic_visit(node).lines
 167             self.lines.extend(['.. admonition:: Deprecated'] + ['   ' + s for s in sublines])
 168         else:
 169             raise ValueError(node)
 170
 171     def visit_subscript(self, node):
 172         self.lines[-1] += '\ :sub:`%s` %s' % (node.text, node.tail)
 173
 174
 175 ##########################################################################
 176 # Directives
 177 ##########################################################################
 178
 179
 180 class DoxygenDocumenter(Documenter):
 181     # Variables to store the names of the object being documented. modname and fullname are redundant,
 182     # and objpath is always the empty list. This is inelegant, but we need to work with the superclass.
 183
 184     fullname = None  # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName""
 185     modname = None   # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName""
 186     objname = None   # example: "NonbondedForce"  or "methodName"
 187     objpath = []     # always the empty list
 188     object = None    # the xml node for the object
 189
 190     option_spec = {
 191         'members': members_option,
 192     }
 193
 194     def __init__(self, directive, name, indent=u'', my_id = None):
 195         super(DoxygenDocumenter, self).__init__(directive, name, indent)
 196         if my_id is not None:
 197             self.parse_id(my_id)
 198
 199     def parse_id(self, id_to_parse):
 200         return False
 201
 202     def parse_name(self):
 203         """Determine what module to import and what attribute to document.
 204         Returns True and sets *self.modname*, *self.objname*, *self.fullname*,
 205         if parsing and resolving was successful.
 206         """
 207         # To view the context and order in which all of these methods get called,
 208         # See, Documenter.generate(). That's the main "entry point" that first
 209         # calls parse_name(), follwed by import_object(), format_signature(),
 210         # add_directive_header(), and then add_content() (which calls get_doc())
 211
 212         # If we were provided a prototype, that must be an overloaded function. Save it.
 213         self.argsstring = None
 214         if "(" in self.name:
 215             (self.name, self.argsstring) = self.name.split('(', 1)
 216             self.argsstring = "({}".format(self.argsstring)
 217
 218         # methods in the superclass sometimes use '.' to join namespace/class
 219         # names with method names, and we don't want that.
 220         self.name = self.name.replace('.', '::')
 221         self.fullname = self.name
 222         self.modname = self.fullname
 223         self.objpath = []
 224
 225         if '::' in self.name:
 226             parts = self.name.split('::')
 227             self.klassname = parts[-2]
 228             self.objname = parts[-1]
 229         else:
 230             self.objname = self.name
 231             self.klassname = ""
 232
 233         return True
 234
 235     def add_directive_header(self, sig):
 236         """Add the directive header and options to the generated content."""
 237         domain = getattr(self, 'domain', 'cpp')
 238         directive = getattr(self, 'directivetype', self.objtype)
 239         name = self.format_name()
 240         sourcename = self.get_sourcename()
 241         #print('.. %s:%s:: %s%s' % (domain, directive, name, sig))
 242         self.add_line(u'.. %s:%s:: %s%s' % (domain, directive, name, sig),
 243                       sourcename)
 244
 245     def document_members(self, all_members=False):
 246         """Generate reST for member documentation.
 247         If *all_members* is True, do all members, else those given by
 248         *self.options.members*.
 249         """
 250         want_all = all_members or self.options.inherited_members or \
 251             self.options.members is ALL
 252         # find out which members are documentable
 253         members_check_module, members = self.get_object_members(want_all)
 254
 255         # remove members given by exclude-members
 256         if self.options.exclude_members:
 257             members = [(membername, member) for (membername, member) in members
 258                        if membername not in self.options.exclude_members]
 259
 260         # document non-skipped members
 261         memberdocumenters = []
 262         for (mname, member, isattr) in self.filter_members(members, want_all):
 263             classes = [cls for cls in itervalues(AutoDirective._registry)
 264                        if cls.can_document_member(member, mname, isattr, self)]
 265             if not classes:
 266                 # don't know how to document this member
 267                 continue
 268
 269             # prefer the documenter with the highest priority
 270             classes.sort(key=lambda cls: cls.priority)
 271
 272             documenter = classes[-1](self.directive, mname, indent=self.indent, id=member.get('id'))
 273             memberdocumenters.append((documenter, isattr))
 274
 275         for documenter, isattr in memberdocumenters:
 276             documenter.generate(
 277                 all_members=True, real_modname=self.real_modname,
 278                 check_module=members_check_module and not isattr)
 279
 280         # reset current objects
 281         self.env.temp_data['autodoc:module'] = None
 282         self.env.temp_data['autodoc:class'] = None
 283
 284
 285 class DoxygenClassDocumenter(DoxygenDocumenter):
 286     objtype = 'doxyclass'
 287     directivetype = 'class'
 288     domain = 'cpp'
 289     priority = 100
 290
 291     option_spec = {
 292         'members': members_option,
 293     }
 294
 295     @classmethod
 296     def can_document_member(cls, member, membername, isattr, parent):
 297         # this method is only called from Documenter.document_members
 298         # when a higher level documenter (module or namespace) is trying
 299         # to choose the appropriate documenter for each of its lower-level
 300         # members. Currently not implemented since we don't have a higher-level
 301         # doumenter like a DoxygenNamespaceDocumenter.
 302         return False
 303
 304     def import_object(self):
 305         """Import the object and set it as *self.object*.  In the call sequence, this
 306         is executed right after parse_name(), so it can use *self.fullname*, *self.objname*,
 307         and *self.modname*.
 308
 309         Returns True if successful, False if an error occurred.
 310         """
 311         xpath_query = './/compoundname[text()="%s"]/..' % self.fullname
 312         match = get_doxygen_root().xpath(xpath_query)
 313         if len(match) != 1:
 314             raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried'
 315                                  'the following xpath: "%s"' % (self.fullname, xpath_query))
 316
 317         self.object = match[0]
 318         return True
 319
 320     def format_signature(self):
 321         return ''
 322
 323     def format_name(self):
 324         return self.fullname
 325
 326     def get_doc(self, encoding):
 327         detaileddescription = self.object.find('detaileddescription')
 328         doc = [format_xml_paragraph(detaileddescription)]
 329         return doc
 330
 331     def get_object_members(self, want_all):
 332         all_members = self.object.xpath('.//sectiondef[@kind="public-func" '
 333             'or @kind="public-static-func"]/memberdef[@kind="function"]')
 334
 335         if want_all:
 336             return False, ((m.find('name').text, m) for m in all_members)
 337         if not self.options.members:
 338             return False, []
 339         return False, ((m.find('name').text, m) for m in all_members if m.find('name').text in self.options.members)
 340
 341     def filter_members(self, members, want_all):
 342         ret = []
 343         for (membername, member) in members:
 344             ret.append((membername, member, False))
 345         return ret
 346
 347     def document_members(self, all_members=False):
 348         super(DoxygenClassDocumenter, self).document_members(all_members=all_members)
 349         # Uncomment to view the generated rst for the class.
 350         # print('\n'.join(self.directive.result))
 351
 352 class DoxygenMethodDocumenter(DoxygenDocumenter):
 353     objtype = 'doxymethod'
 354     directivetype = 'function'
 355     domain = 'cpp'
 356     priority = 100
 357
 358     @classmethod
 359     def can_document_member(cls, member, membername, isattr, parent):
 360         if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'function':
 361             return True
 362         return False
 363
 364     def parse_id(self, id_to_parse):
 365         xp = './/*[@id="%s"]' % id_to_parse
 366         match = get_doxygen_root().xpath(xp)
 367         if match:
 368             match = match[0]
 369             self.fullname = match.find('./definition').text.split()[-1]
 370             self.modname = self.fullname
 371             self.objname = match.find('./name').text
 372             self.object = match
 373         return False
 374
 375     def import_object(self):
 376         if ET.iselement(self.object):
 377             # self.object already set from DoxygenDocumenter.parse_name(),
 378             # caused by passing in the `id` of the node instead of just a
 379             # classname or method name
 380             return True
 381
 382         if '::' in self.fullname:
 383             (obj, meth) = self.fullname.rsplit('::', 1)
 384             # 'public-func' and 'public-static-func' are for classes while 'func' alone is for namespaces
 385             prefix = './/compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func" or @kind="func"]'.format(obj)
 386             obj = "{:s}::".format(obj)
 387         else:
 388             meth = self.fullname
 389             prefix = './'
 390             obj = ''
 391
 392         xpath_query_noparam = ('{:s}/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(prefix, meth)
 393         xpath_query = ""
 394         if self.argsstring != None:
 395             xpath_query = ('{:s}/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(prefix,self.argsstring,meth)
 396         else:
 397             xpath_query = xpath_query_noparam
 398         match = get_doxygen_root().xpath(xpath_query)
 399         if not match:
 400             logger = logging.getLogger(__name__)
 401
 402             if self.argsstring != None:
 403                 candidates = get_doxygen_root().xpath(xpath_query_noparam)
 404                 if len(candidates) == 1:
 405                     logger.warning("[autodoxy] Using method '{}{}{}' instead of '{}{}{}'. You may want to drop your specification of the signature, or to fix it."
 406                                    .format(obj, meth, candidates[0].find('argsstring').text, obj, meth, self.argsstring))
 407                     self.object = candidates[0]
 408                     return True
 409                 logger.warning("[autodoxy] WARNING: Could not find method {}{}{}".format(obj, meth, self.argsstring))
 410                 if not candidates:
 411                     logger.warning("[autodoxy] WARNING:  (no candidate found)")
 412                 for cand in candidates:
 413                     logger.warning("[autodoxy] WARNING:   Existing candidate: {}{}{}".format(obj, meth, cand.find('argsstring').text))
 414             else:
 415                 logger.warning("[autodoxy] WARNING: Could not find method {}{} in Doxygen files\nQuery: {}".format(obj, meth, xpath_query))
 416             return False
 417         self.object = match[0]
 418         return True
 419
 420     def get_doc(self, encoding):
 421         detaileddescription = self.object.find('detaileddescription')
 422         doc = [format_xml_paragraph(detaileddescription)]
 423         return doc
 424
 425     def format_name(self):
 426         def text(el):
 427             if el.text is not None:
 428                 return el.text
 429             return ''
 430
 431         def tail(el):
 432             if el.tail is not None:
 433                 return el.tail
 434             return ''
 435
 436         rtype_el = self.object.find('type')
 437         rtype_el_ref = rtype_el.find('ref')
 438         if rtype_el_ref is not None:
 439             rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
 440         else:
 441             rtype = rtype_el.text
 442
 443  #       print("rtype: {}".format(rtype))
 444         signame = (rtype and (rtype + ' ') or '') + self.klassname + "::"+ self.objname
 445         return self.format_template_name() + signame
 446
 447     def format_template_name(self):
 448         types = [e.text for e in self.object.findall('templateparamlist/param/type')]
 449         if not types:
 450             return ''
 451         ret = 'template <%s>' % ','.join(types)
 452 #        print ("template: {}".format(ret))
 453         return ret
 454
 455     def format_signature(self):
 456         args = self.object.find('argsstring').text
 457         return args
 458
 459     def document_members(self, all_members=False):
 460         pass
 461
 462 class DoxygenVariableDocumenter(DoxygenDocumenter):
 463     objtype = 'doxyvar'
 464     directivetype = 'var'
 465     domain = 'cpp'
 466     priority = 100
 467
 468     @classmethod
 469     def can_document_member(cls, member, membername, isattr, parent):
 470         if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'variable':
 471             return True
 472         return False
 473
 474     def import_object(self):
 475         if ET.iselement(self.object):
 476             # self.object already set from DoxygenDocumenter.parse_name(),
 477             # caused by passing in the `id` of the node instead of just a
 478             # classname or method name
 479             return True
 480
 481         (obj, var) = self.fullname.rsplit('::', 1)
 482
 483         xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-attrib" or @kind="public-static-attrib"]'
 484                        '/memberdef[@kind="variable"]/name[text()="{:s}"]/..').format(obj, var)
 485 #        print("fullname {}".format(self.fullname))
 486         match = get_doxygen_root().xpath(xpath_query)
 487         if not match:
 488             logger = logging.getLogger(__name__)
 489
 490             logger.warning("[autodoxy] WARNING: could not find variable {}::{} in Doxygen files".format(obj, var))
 491             return False
 492         self.object = match[0]
 493         return True
 494
 495     def parse_id(self, id_to_parse):
 496         xp = './/*[@id="%s"]' % id_to_parse
 497         match = get_doxygen_root().xpath(xp)
 498         if match:
 499             match = match[0]
 500             self.fullname = match.find('./definition').text.split()[-1]
 501             self.modname = self.fullname
 502             self.objname = match.find('./name').text
 503             self.object = match
 504         return False
 505
 506     def format_name(self):
 507         def text(el):
 508             if el.text is not None:
 509                 return el.text
 510             return ''
 511
 512         def tail(el):
 513             if el.tail is not None:
 514                 return el.tail
 515             return ''
 516
 517         rtype_el = self.object.find('type')
 518         rtype_el_ref = rtype_el.find('ref')
 519         if rtype_el_ref is not None:
 520             rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
 521         else:
 522             rtype = rtype_el.text
 523
 524  #       print("rtype: {}".format(rtype))
 525         signame = (rtype and (rtype + ' ') or '') + self.klassname + "::" + self.objname
 526         return self.format_template_name() + signame
 527
 528     def get_doc(self, encoding):
 529         detaileddescription = self.object.find('detaileddescription')
 530         doc = [format_xml_paragraph(detaileddescription)]
 531         return doc
 532
 533     def format_template_name(self):
 534         types = [e.text for e in self.object.findall('templateparamlist/param/type')]
 535         if not types:
 536             return ''
 537         ret = 'template <%s>' % ','.join(types)
 538 #        print ("template: {}".format(ret))
 539         return ret
 540
 541     def document_members(self, all_members=False):
 542         pass
 543
 544
 545 ##########################################################################
 546 # Setup the extension
 547 ##########################################################################
 548 def set_doxygen_xml(app):
 549     """Load all doxygen XML files from the app config variable
 550     `app.config.doxygen_xml` which should be a path to a directory
 551     containing doxygen xml output
 552     """
 553     err = ExtensionError(
 554         '[autodoxy] No doxygen xml output found in doxygen_xml="%s"' % app.config.doxygen_xml)
 555
 556     if not os.path.isdir(app.config.doxygen_xml):
 557         raise err
 558
 559     files = [os.path.join(app.config.doxygen_xml, f)
 560              for f in os.listdir(app.config.doxygen_xml)
 561              if f.lower().endswith('.xml') and not f.startswith('._')]
 562     if not files:
 563         raise err
 564
 565     setup.DOXYGEN_ROOT = ET.ElementTree(ET.Element('root')).getroot()
 566     for current_file in files:
 567         root = ET.parse(current_file).getroot()
 568         for node in root:
 569             setup.DOXYGEN_ROOT.append(node)
 570
 571
 572 def get_doxygen_root():
 573     """Get the root element of the doxygen XML document.
 574     """
 575     if not hasattr(setup, 'DOXYGEN_ROOT'):
 576         setup.DOXYGEN_ROOT = ET.Element("root")  # dummy
 577     return setup.DOXYGEN_ROOT
 578
 579
 580 def setup(app):
 581     import sphinx.ext.autosummary
 582
 583     app.connect("builder-inited", set_doxygen_xml)
 584 #    app.connect("builder-inited", process_generate_options)
 585
 586     app.setup_extension('sphinx.ext.autodoc')
 587 #    app.setup_extension('sphinx.ext.autosummary')
 588
 589     app.add_autodocumenter(DoxygenClassDocumenter)
 590     app.add_autodocumenter(DoxygenMethodDocumenter)
 591     app.add_autodocumenter(DoxygenVariableDocumenter)
 592     app.add_config_value("doxygen_xml", "", True)
 593
 594 #    app.add_directive('autodoxysummary', DoxygenAutosummary)
 595 #    app.add_directive('autodoxyenum', DoxygenAutoEnum)
 596
 597     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}