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             prefix = './/compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'.format(obj)
 385             obj = "{:s}::".format(obj)
 386         else:
 387             meth = self.fullname
 388             prefix = './'
 389             obj = ''
 390
 391         xpath_query_noparam = ('{:s}/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(prefix, meth)
 392         xpath_query = ""
 393         if self.argsstring != None:
 394             xpath_query = ('{:s}/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(prefix,self.argsstring,meth)
 395         else:
 396             xpath_query = xpath_query_noparam
 397         match = get_doxygen_root().xpath(xpath_query)
 398         if not match:
 399             logger = logging.getLogger(__name__)
 400
 401             if self.argsstring != None:
 402                 candidates = get_doxygen_root().xpath(xpath_query_noparam)
 403                 if len(candidates) == 1:
 404                     logger.warning("[autodoxy] Using method '{}{}{}' instead of '{}{}{}'. You may want to drop your specification of the signature, or to fix it."
 405                                    .format(obj, meth, candidates[0].find('argsstring').text, obj, meth, self.argsstring))
 406                     self.object = candidates[0]
 407                     return True
 408                 logger.warning("[autodoxy] WARNING: Could not find method {}{}{}".format(obj, meth, self.argsstring))
 409                 for cand in candidates:
 410                     logger.warning("[autodoxy] WARNING:   Existing candidate: {}{}{}".format(obj, meth, cand.find('argsstring').text))
 411             else:
 412                 logger.warning("[autodoxy] WARNING: could not find method {}{} in Doxygen files\nQuery: {}".format(obj, meth, xpath_query))
 413             return False
 414         self.object = match[0]
 415         return True
 416
 417     def get_doc(self, encoding):
 418         detaileddescription = self.object.find('detaileddescription')
 419         doc = [format_xml_paragraph(detaileddescription)]
 420         return doc
 421
 422     def format_name(self):
 423         def text(el):
 424             if el.text is not None:
 425                 return el.text
 426             return ''
 427
 428         def tail(el):
 429             if el.tail is not None:
 430                 return el.tail
 431             return ''
 432
 433         rtype_el = self.object.find('type')
 434         rtype_el_ref = rtype_el.find('ref')
 435         if rtype_el_ref is not None:
 436             rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
 437         else:
 438             rtype = rtype_el.text
 439
 440  #       print("rtype: {}".format(rtype))
 441         signame = (rtype and (rtype + ' ') or '') + self.klassname + "::"+ self.objname
 442         return self.format_template_name() + signame
 443
 444     def format_template_name(self):
 445         types = [e.text for e in self.object.findall('templateparamlist/param/type')]
 446         if not types:
 447             return ''
 448         ret = 'template <%s>' % ','.join(types)
 449 #        print ("template: {}".format(ret))
 450         return ret
 451
 452     def format_signature(self):
 453         args = self.object.find('argsstring').text
 454         return args
 455
 456     def document_members(self, all_members=False):
 457         pass
 458
 459 class DoxygenVariableDocumenter(DoxygenDocumenter):
 460     objtype = 'doxyvar'
 461     directivetype = 'var'
 462     domain = 'cpp'
 463     priority = 100
 464
 465     @classmethod
 466     def can_document_member(cls, member, membername, isattr, parent):
 467         if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'variable':
 468             return True
 469         return False
 470
 471     def import_object(self):
 472         if ET.iselement(self.object):
 473             # self.object already set from DoxygenDocumenter.parse_name(),
 474             # caused by passing in the `id` of the node instead of just a
 475             # classname or method name
 476             return True
 477
 478         (obj, var) = self.fullname.rsplit('::', 1)
 479
 480         xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-attrib" or @kind="public-static-attrib"]'
 481                        '/memberdef[@kind="variable"]/name[text()="{:s}"]/..').format(obj, var)
 482 #        print("fullname {}".format(self.fullname))
 483         match = get_doxygen_root().xpath(xpath_query)
 484         if not match:
 485             logger = logging.getLogger(__name__)
 486
 487             logger.warning("[autodoxy] WARNING: could not find variable {}::{} in Doxygen files".format(obj, var))
 488             return False
 489         self.object = match[0]
 490         return True
 491
 492     def parse_id(self, id_to_parse):
 493         xp = './/*[@id="%s"]' % id_to_parse
 494         match = get_doxygen_root().xpath(xp)
 495         if match:
 496             match = match[0]
 497             self.fullname = match.find('./definition').text.split()[-1]
 498             self.modname = self.fullname
 499             self.objname = match.find('./name').text
 500             self.object = match
 501         return False
 502
 503     def format_name(self):
 504         def text(el):
 505             if el.text is not None:
 506                 return el.text
 507             return ''
 508
 509         def tail(el):
 510             if el.tail is not None:
 511                 return el.tail
 512             return ''
 513
 514         rtype_el = self.object.find('type')
 515         rtype_el_ref = rtype_el.find('ref')
 516         if rtype_el_ref is not None:
 517             rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref)
 518         else:
 519             rtype = rtype_el.text
 520
 521  #       print("rtype: {}".format(rtype))
 522         signame = (rtype and (rtype + ' ') or '') + self.klassname + "::" + self.objname
 523         return self.format_template_name() + signame
 524
 525     def get_doc(self, encoding):
 526         detaileddescription = self.object.find('detaileddescription')
 527         doc = [format_xml_paragraph(detaileddescription)]
 528         return doc
 529
 530     def format_template_name(self):
 531         types = [e.text for e in self.object.findall('templateparamlist/param/type')]
 532         if not types:
 533             return ''
 534         ret = 'template <%s>' % ','.join(types)
 535 #        print ("template: {}".format(ret))
 536         return ret
 537
 538     def document_members(self, all_members=False):
 539         pass
 540
 541
 542 ##########################################################################
 543 # Setup the extension
 544 ##########################################################################
 545 def set_doxygen_xml(app):
 546     """Load all doxygen XML files from the app config variable
 547     `app.config.doxygen_xml` which should be a path to a directory
 548     containing doxygen xml output
 549     """
 550     err = ExtensionError(
 551         '[autodoxy] No doxygen xml output found in doxygen_xml="%s"' % app.config.doxygen_xml)
 552
 553     if not os.path.isdir(app.config.doxygen_xml):
 554         raise err
 555
 556     files = [os.path.join(app.config.doxygen_xml, f)
 557              for f in os.listdir(app.config.doxygen_xml)
 558              if f.lower().endswith('.xml') and not f.startswith('._')]
 559     if not files:
 560         raise err
 561
 562     setup.DOXYGEN_ROOT = ET.ElementTree(ET.Element('root')).getroot()
 563     for current_file in files:
 564         root = ET.parse(current_file).getroot()
 565         for node in root:
 566             setup.DOXYGEN_ROOT.append(node)
 567
 568
 569 def get_doxygen_root():
 570     """Get the root element of the doxygen XML document.
 571     """
 572     if not hasattr(setup, 'DOXYGEN_ROOT'):
 573         setup.DOXYGEN_ROOT = ET.Element("root")  # dummy
 574     return setup.DOXYGEN_ROOT
 575
 576
 577 def setup(app):
 578     import sphinx.ext.autosummary
 579
 580     app.connect("builder-inited", set_doxygen_xml)
 581 #    app.connect("builder-inited", process_generate_options)
 582
 583     app.setup_extension('sphinx.ext.autodoc')
 584 #    app.setup_extension('sphinx.ext.autosummary')
 585
 586     app.add_autodocumenter(DoxygenClassDocumenter)
 587     app.add_autodocumenter(DoxygenMethodDocumenter)
 588     app.add_autodocumenter(DoxygenVariableDocumenter)
 589     app.add_config_value("doxygen_xml", "", True)
 590
 591 #    app.add_directive('autodoxysummary', DoxygenAutosummary)
 592 #    app.add_directive('autodoxyenum', DoxygenAutoEnum)
 593
 594     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}