X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/583414a74fd05a190c78ca89881756ac1eaaee3d..88da900bc8d43401167e64b7f55c49be6164c85f:/docs/source/_ext/autodoxy.py diff --git a/docs/source/_ext/autodoxy.py b/docs/source/_ext/autodoxy.py deleted file mode 100644 index 3b277efdfd..0000000000 --- a/docs/source/_ext/autodoxy.py +++ /dev/null @@ -1,641 +0,0 @@ -""" -This is autodoxy, a sphinx extension providing autodoc-like directives -that are feed with Doxygen files. - -It is highly inspired from the autodoc_doxygen sphinx extension, but -adapted to my own needs in SimGrid. -https://github.com/rmcgibbo/sphinxcontrib-autodoc_doxygen - -Licence: MIT -Copyright (c) 2015 Robert T. McGibbon -Copyright (c) 2019 Martin Quinson -""" -from __future__ import print_function, absolute_import, division - -import os.path -import re -import sys -import traceback # debug, big time - -from six import itervalues -from lxml import etree as ET -from sphinx.ext.autodoc import Documenter, members_option, ALL -try: - from sphinx.ext.autodoc import AutoDirective - sphinxVersion = 1 -except ImportError: - sphinxVersion = 2 -from sphinx.errors import ExtensionError -from sphinx.util import logging - -########################################################################## -# XML utils -########################################################################## -def format_xml_paragraph(xmlnode): - """Format an Doxygen XML segment (principally a detaileddescription) - as a paragraph for inclusion in the rst document - - Parameters - ---------- - xmlnode - - Returns - ------- - lines - A list of lines. - """ - return [l.rstrip() for l in _DoxygenXmlParagraphFormatter().generic_visit(xmlnode).lines] - -def elm2xml(xelm): - """Return the unparsed form of the element""" - res = '<{}'.format(xelm.tag) - for key in xelm.keys(): - res += ' {}="{}"'.format(key, xelm.attrib[key]) - res += ">" - if xelm.text is not None: # Text before the first child - res += xelm.text - for i in xelm.getchildren(): # serialize every subtag - res += elm2xml(i) - if xelm.tail is not None: # Text after last child - res += xelm.tail - res += ''.format(xelm.tag) - return res -def elm2txt(xelm): - """Return the content of the element, with all tags removed. Only the text remains""" - res = '' - if xelm.text is not None: # Text before the first child - res += xelm.text - for i in xelm.getchildren(): # serialize every subtag - res += elm2txt(i) - if xelm.tail is not None: # Text after last child - res += xelm.tail - return res - -class _DoxygenXmlParagraphFormatter(object): - # This class follows the model of the stdlib's ast.NodeVisitor for tree traversal - # where you dispatch on the element type to a different method for each node - # during the traverse. - - # It's supposed to handle paragraphs, references, preformatted text (code blocks), and lists. - - def __init__(self): - self.lines = [''] - self.continue_line = False - - def visit(self, node): - method = 'visit_' + node.tag - visitor = getattr(self, method, self.generic_visit) - return visitor(node) - - def generic_visit(self, node): - for child in node.getchildren(): - self.visit(child) - return self - - def visit_ref(self, node): - ref = get_doxygen_root().findall('.//*[@id="%s"]' % node.get('refid')) - if ref: - ref = ref[0] - if ref.tag == 'memberdef': - parent = ref.xpath('./ancestor::compounddef/compoundname')[0].text - name = ref.find('./name').text - real_name = parent + '::' + name - elif ref.tag in ('compounddef', 'enumvalue'): - name_node = ref.find('./name') - real_name = name_node.text if name_node is not None else '' - else: - raise NotImplementedError(ref.tag) - else: - real_name = None - - val = [':cpp:any:`', node.text] - if real_name: - val.extend((' <', real_name, '>`')) - else: - val.append('`') - if node.tail is not None: - val.append(node.tail) - - self.lines[-1] += ''.join(val) - - def visit_para(self, node): - if node.text is not None: - if self.continue_line: - self.lines[-1] += node.text - else: - self.lines.append(node.text) - self.generic_visit(node) - self.lines.append('') - self.continue_line = False - - def visit_verbatim(self, node): - if node.text is not None: - # remove the leading ' *' of any lines - lines = [re.sub('^\s*\*','', l) for l in node.text.split('\n')] - # Merge each paragraph together - text = re.sub("\n\n", "PaRaGrraphSplit", '\n'.join(lines)) - text = re.sub('\n', '', text) - lines = text.split('PaRaGrraphSplit') - - # merge content to the built doc - if self.continue_line: - self.lines[-1] += lines[0] - lines = lines[1:] - for l in lines: - self.lines.append('') - self.lines.append(l) - self.generic_visit(node) - self.lines.append('') - self.continue_line = False - - def visit_parametername(self, node): - if 'direction' in node.attrib: - direction = '[%s] ' % node.get('direction') - else: - direction = '' - - self.lines.append('**%s** -- %s' % ( - node.text, direction)) - self.continue_line = True - - def visit_parameterlist(self, node): - lines = [l for l in type(self)().generic_visit(node).lines if l != ''] - self.lines.extend([':parameters:', ''] + ['* %s' % l for l in lines] + ['']) - - def visit_simplesect(self, node): - if node.get('kind') == 'return': - self.lines.append(':returns: ') - self.continue_line = True - self.generic_visit(node) - - def visit_listitem(self, node): - self.lines.append(' - ') - self.continue_line = True - self.generic_visit(node) - - def visit_preformatted(self, node): - segment = [node.text if node.text is not None else ''] - for n in node.getchildren(): - segment.append(n.text) - if n.tail is not None: - segment.append(n.tail) - - lines = ''.join(segment).split('\n') - self.lines.extend(('.. code-block:: C++', '')) - self.lines.extend([' ' + l for l in lines]) - - def visit_computeroutput(self, node): - c = node.find('preformatted') - if c is not None: - return self.visit_preformatted(c) - return self.visit_preformatted(node) - - def visit_xrefsect(self, node): - if node.find('xreftitle').text == 'Deprecated': - sublines = type(self)().generic_visit(node).lines - self.lines.extend(['.. admonition:: Deprecated'] + [' ' + s for s in sublines]) - else: - raise ValueError(node) - - def visit_subscript(self, node): - self.lines[-1] += '\ :sub:`%s` %s' % (node.text, node.tail) - - -########################################################################## -# Directives -########################################################################## - - -class DoxygenDocumenter(Documenter): - # Variables to store the names of the object being documented. modname and fullname are redundant, - # and objpath is always the empty list. This is inelegant, but we need to work with the superclass. - - fullname = None # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName"" - modname = None # example: "OpenMM::NonbondedForce" or "OpenMM::NonbondedForce::methodName"" - objname = None # example: "NonbondedForce" or "methodName" - objpath = [] # always the empty list - object = None # the xml node for the object - - option_spec = { - 'members': members_option, - } - - def __init__(self, directive, name, indent=u'', my_id = None): - super(DoxygenDocumenter, self).__init__(directive, name, indent) - if my_id is not None: - self.parse_id(my_id) - - def parse_id(self, id_to_parse): - return False - - def parse_name(self): - """Determine what module to import and what attribute to document. - Returns True and sets *self.modname*, *self.objname*, *self.fullname*, - if parsing and resolving was successful. - """ - # To view the context and order in which all of these methods get called, - # See, Documenter.generate(). That's the main "entry point" that first - # calls parse_name(), follwed by import_object(), format_signature(), - # add_directive_header(), and then add_content() (which calls get_doc()) - - # If we were provided a prototype, that must be an overloaded function. Save it. - self.argsstring = None - if "(" in self.name: - (self.name, self.argsstring) = self.name.split('(', 1) - self.argsstring = "({}".format(self.argsstring) - - # methods in the superclass sometimes use '.' to join namespace/class - # names with method names, and we don't want that. - self.name = self.name.replace('.', '::') - self.fullname = self.name - self.modname = self.fullname - self.objpath = [] - - if '::' in self.name: - parts = self.name.split('::') - self.klassname = parts[-2] - self.objname = parts[-1] - else: - self.objname = self.name - self.klassname = "" - - return True - - def add_directive_header(self, sig): - """Add the directive header and options to the generated content.""" - domain = getattr(self, 'domain', 'cpp') - directive = getattr(self, 'directivetype', self.objtype) - name = self.format_name() - sourcename = self.get_sourcename() - #print('.. %s:%s:: %s%s' % (domain, directive, name, sig)) - self.add_line(u'.. %s:%s:: %s%s' % (domain, directive, name, sig), - sourcename) - - def document_members(self, all_members=False): - """Generate reST for member documentation. - If *all_members* is True, do all members, else those given by - *self.options.members*. - """ - want_all = all_members or self.options.inherited_members or \ - self.options.members is ALL - # find out which members are documentable - members_check_module, members = self.get_object_members(want_all) - - # remove members given by exclude-members - if self.options.exclude_members: - members = [(membername, member) for (membername, member) in members - if membername not in self.options.exclude_members] - - # document non-skipped members - memberdocumenters = [] - for (mname, member, isattr) in self.filter_members(members, want_all): - if sphinxVersion >= 2: - classes = [cls for cls in itervalues(self.env.app.registry.documenters) - if cls.can_document_member(member, mname, isattr, self)] - else: - classes = [cls for cls in itervalues(AutoDirective._registry) - if cls.can_document_member(member, mname, isattr, self)] - if not classes: - # don't know how to document this member - continue - - # prefer the documenter with the highest priority - classes.sort(key=lambda cls: cls.priority) - - documenter = classes[-1](self.directive, mname, indent=self.indent, id=member.get('id')) - memberdocumenters.append((documenter, isattr)) - - for documenter, isattr in memberdocumenters: - documenter.generate( - all_members=True, real_modname=self.real_modname, - check_module=members_check_module and not isattr) - - # reset current objects - self.env.temp_data['autodoc:module'] = None - self.env.temp_data['autodoc:class'] = None - - -class DoxygenClassDocumenter(DoxygenDocumenter): - objtype = 'doxyclass' - directivetype = 'class' - domain = 'cpp' - priority = 100 - - option_spec = { - 'members': members_option, - } - - @classmethod - def can_document_member(cls, member, membername, isattr, parent): - # this method is only called from Documenter.document_members - # when a higher level documenter (module or namespace) is trying - # to choose the appropriate documenter for each of its lower-level - # members. Currently not implemented since we don't have a higher-level - # doumenter like a DoxygenNamespaceDocumenter. - return False - - def import_object(self): - """Import the object and set it as *self.object*. In the call sequence, this - is executed right after parse_name(), so it can use *self.fullname*, *self.objname*, - and *self.modname*. - - Returns True if successful, False if an error occurred. - """ - xpath_query = './/compoundname[text()="%s"]/..' % self.fullname - match = get_doxygen_root().xpath(xpath_query) - if len(match) != 1: - raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried ' - 'the following xpath: "%s"' % (self.fullname, xpath_query)) - - self.object = match[0] - return True - - def format_signature(self): - return '' - - def format_name(self): - return self.fullname - - def get_doc(self, encoding=None): # This method is called with 1 parameter in Sphinx 2.x and 2 parameters in Sphinx 1.x - detaileddescription = self.object.find('detaileddescription') - doc = [format_xml_paragraph(detaileddescription)] - return doc - - def get_object_members(self, want_all): - all_members = self.object.xpath('.//sectiondef[@kind="public-func" ' - 'or @kind="public-static-func"]/memberdef[@kind="function"]') - - if want_all: - return False, ((m.find('name').text, m) for m in all_members) - if not self.options.members: - return False, [] - return False, ((m.find('name').text, m) for m in all_members if m.find('name').text in self.options.members) - - def filter_members(self, members, want_all): - ret = [] - for (membername, member) in members: - ret.append((membername, member, False)) - return ret - - def document_members(self, all_members=False): - super(DoxygenClassDocumenter, self).document_members(all_members=all_members) - # Uncomment to view the generated rst for the class. - # print('\n'.join(self.directive.result)) - -autodoxy_requalified_identifiers = [] -def fix_namespaces(str): - for unqualified,fullyqualif in autodoxy_requalified_identifiers: - p = re.compile("(^| ){:s}".format(unqualified)) - str = p.sub(' {:s}'.format(fullyqualif), str) - return str - -class DoxygenMethodDocumenter(DoxygenDocumenter): - objtype = 'doxymethod' - directivetype = 'function' - domain = 'cpp' - priority = 100 - - @classmethod - def can_document_member(cls, member, membername, isattr, parent): - if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'function': - return True - return False - - def parse_id(self, id_to_parse): - print("Parse ID {}".format(id_to_parse)) - xp = './/*[@id="%s"]' % id_to_parse - match = get_doxygen_root().xpath(xp) - if match: - match = match[0] - print("ID: {}".format(elm2xml(match))) - self.fullname = match.find('./definition').text.split()[-1] - self.modname = self.fullname - self.objname = match.find('./name').text - self.object = match - return False - - def import_object(self): - if ET.iselement(self.object): - # self.object already set from DoxygenDocumenter.parse_name(), - # caused by passing in the `id` of the node instead of just a - # classname or method name - return True - -# sys.stderr.write("fullname: {}".format(self.fullname)) -# traceback.print_stack() - if '::' in self.fullname: - (obj, meth) = self.fullname.rsplit('::', 1) - # 'public-func' and 'public-static-func' are for classes while 'func' alone is for namespaces - prefix = './/compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func" or @kind="func"]'.format(obj) - obj = "{:s}::".format(obj) - else: - meth = self.fullname - prefix = './' - obj = '' - - xpath_query_noparam = ('{:s}/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(prefix, meth) - xpath_query = "" - if self.argsstring is not None: - xpath_query = ('{:s}/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(prefix,self.argsstring,meth) - else: - xpath_query = xpath_query_noparam - match = get_doxygen_root().xpath(xpath_query) - if not match: - logger = logging.getLogger(__name__) - - if self.argsstring is not None: - candidates = get_doxygen_root().xpath(xpath_query_noparam) - if len(candidates) == 1: - logger.warning("[autodoxy] Using method '{}{}{}' instead of '{}{}{}'. You may want to drop your specification of the signature, or to fix it." - .format(obj, meth, candidates[0].find('argsstring').text, obj, meth, self.argsstring)) - self.object = candidates[0] - return True - logger.warning("[autodoxy] WARNING: Could not find method {}{}{}".format(obj, meth, self.argsstring)) - if not candidates: - logger.warning("[autodoxy] WARNING: (no candidate found)") - logger.warning("Query was: {}".format(xpath_query)) - for cand in candidates: - logger.warning("[autodoxy] WARNING: Existing candidate: {}{}{}".format(obj, meth, cand.find('argsstring').text)) - else: - logger.warning("[autodoxy] WARNING: Could not find method {}{} in Doxygen files\nQuery: {}".format(obj, meth, xpath_query)) - return False - self.object = match[0] - return True - - def get_doc(self, encoding=None): # This method is called with 1 parameter in Sphinx 2.x and 2 parameters in Sphinx 1.x - detaileddescription = self.object.find('detaileddescription') - doc = [format_xml_paragraph(detaileddescription)] - return doc - - def format_name(self): - def text(el): - if el.text is not None: - return el.text - return '' - - def tail(el): - if el.tail is not None: - return el.tail - return '' - - rtype_el = self.object.find('type') - rtype_el_ref = rtype_el.find('ref') - if rtype_el_ref is not None: - rtype = text(rtype_el) + text(rtype_el_ref) + tail(rtype_el_ref) - else: - rtype = rtype_el.text - - # print("rtype: {}".format(rtype)) - signame = fix_namespaces((rtype and (rtype + ' ') or '') + self.klassname + "::"+ self.objname ) -# print("signame: '{}'".format(signame)) - return self.format_template_name() + signame - - def format_template_name(self): - types = [e.text for e in self.object.findall('templateparamlist/param/type')] - if not types: - return '' - ret = 'template <%s>' % ','.join(types) -# print ("template: {}".format(ret)) - return ret - - def format_signature(self): - args = fix_namespaces(self.object.find('argsstring').text) -# print ("signature: {}".format(args)) - return args - - def document_members(self, all_members=False): - pass - -class DoxygenVariableDocumenter(DoxygenDocumenter): - objtype = 'doxyvar' - directivetype = 'var' - domain = 'cpp' - priority = 100 - - @classmethod - def can_document_member(cls, member, membername, isattr, parent): - if ET.iselement(member) and member.tag == 'memberdef' and member.get('kind') == 'variable': - return True - return False - - def import_object(self): - if ET.iselement(self.object): - # self.object already set from DoxygenDocumenter.parse_name(), - # caused by passing in the `id` of the node instead of just a - # classname or method name - return True - - (obj, var) = self.fullname.rsplit('::', 1) - - xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-attrib" or @kind="public-static-attrib"]' - '/memberdef[@kind="variable"]/name[text()="{:s}"]/..').format(obj, var) -# print("fullname {}".format(self.fullname)) - match = get_doxygen_root().xpath(xpath_query) - if not match: - logger = logging.getLogger(__name__) - - logger.warning("[autodoxy] WARNING: could not find variable {}::{} in Doxygen files".format(obj, var)) - return False - self.object = match[0] - return True - - def parse_id(self, id_to_parse): - xp = './/*[@id="%s"]' % id_to_parse - match = get_doxygen_root().xpath(xp) - if match: - match = match[0] - self.fullname = match.find('./definition').text.split()[-1] - self.modname = self.fullname - self.objname = match.find('./name').text - self.object = match - return False - - def format_name(self): - def text(el): - if el.text is not None: - return el.text - return '' - - # Remove all tags (such as refs) but keep the text of the element's type - rtype = elm2txt(self.object.find('type')).replace("\n", " ") - rtype = re.sub(" +", " ", rtype) # s/ +/ / - signame = (rtype and (rtype + ' ') or '') + self.klassname + "::" + self.objname - res = fix_namespaces(self.format_template_name() + signame) -# print("formatted name: {}".format(res)) - return res - - def get_doc(self, encoding=None): # This method is called with 1 parameter in Sphinx 2.x and 2 parameters in Sphinx 1.x - detaileddescription = self.object.find('detaileddescription') - doc = [format_xml_paragraph(detaileddescription)] -# print ("doc: {}".format(doc)) - return doc - - def format_template_name(self): - types = [e.text for e in self.object.findall('templateparamlist/param/type')] - if not types: - return '' - ret = 'template <%s>' % ','.join(types) -# print ("template: {}".format(ret)) - return ret - - def document_members(self, all_members=False): - pass - - -########################################################################## -# Setup the extension -########################################################################## -def set_doxygen_xml(app): - """Load all doxygen XML files from the app config variable - `app.config.doxygen_xml` which should be a path to a directory - containing doxygen xml output - """ - err = ExtensionError( - '[autodoxy] No doxygen xml output found in doxygen_xml="%s"' % app.config.doxygen_xml) - - if not os.path.isdir(app.config.doxygen_xml): - raise err - - files = [os.path.join(app.config.doxygen_xml, f) - for f in os.listdir(app.config.doxygen_xml) - if f.lower().endswith('.xml') and not f.startswith('._')] - if not files: - raise err - - setup.DOXYGEN_ROOT = ET.ElementTree(ET.Element('root')).getroot() - for current_file in files: - root = ET.parse(current_file).getroot() - for node in root: - setup.DOXYGEN_ROOT.append(node) - - if app.config.autodoxy_requalified_identifiers is not None: - global autodoxy_requalified_identifiers - autodoxy_requalified_identifiers = app.config.autodoxy_requalified_identifiers - -def get_doxygen_root(): - """Get the root element of the doxygen XML document. - """ - if not hasattr(setup, 'DOXYGEN_ROOT'): - setup.DOXYGEN_ROOT = ET.Element("root") # dummy - return setup.DOXYGEN_ROOT - - -def setup(app): - import sphinx.ext.autosummary - - app.connect("builder-inited", set_doxygen_xml) -# app.connect("builder-inited", process_generate_options) - - app.setup_extension('sphinx.ext.autodoc') -# app.setup_extension('sphinx.ext.autosummary') - - app.add_autodocumenter(DoxygenClassDocumenter) - app.add_autodocumenter(DoxygenMethodDocumenter) - app.add_autodocumenter(DoxygenVariableDocumenter) - app.add_config_value("doxygen_xml", "", True) - app.add_config_value("autodoxy_requalified_identifiers", [], True) - -# app.add_directive('autodoxysummary', DoxygenAutosummary) -# app.add_directive('autodoxyenum', DoxygenAutoEnum) - - return {'version': sphinx.__display_version__, 'parallel_read_safe': True}