X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/63c219ee10cf464f95ad9888e0814439445b53f8..9207441713687a778ea97ffc4142fa5e303e52a5:/docs/source/_ext/autodoxy.py diff --git a/docs/source/_ext/autodoxy.py b/docs/source/_ext/autodoxy.py index 0ee926041b..e607ba9140 100644 --- a/docs/source/_ext/autodoxy.py +++ b/docs/source/_ext/autodoxy.py @@ -18,7 +18,12 @@ import sys from six import itervalues from lxml import etree as ET -from sphinx.ext.autodoc import Documenter, AutoDirective, members_option, ALL +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 @@ -238,6 +243,7 @@ class DoxygenDocumenter(Documenter): 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) @@ -259,8 +265,12 @@ class DoxygenDocumenter(Documenter): # document non-skipped members memberdocumenters = [] for (mname, member, isattr) in self.filter_members(members, want_all): - classes = [cls for cls in itervalues(AutoDirective._registry) - if cls.can_document_member(member, mname, isattr, self)] + 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 @@ -310,7 +320,7 @@ class DoxygenClassDocumenter(DoxygenDocumenter): 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' + raise ExtensionError('[autodoxy] could not find class (fullname="%s"). I tried ' 'the following xpath: "%s"' % (self.fullname, xpath_query)) self.object = match[0] @@ -322,7 +332,7 @@ class DoxygenClassDocumenter(DoxygenDocumenter): def format_name(self): return self.fullname - def get_doc(self, encoding): + 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 @@ -348,6 +358,13 @@ class DoxygenClassDocumenter(DoxygenDocumenter): # 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' @@ -380,7 +397,8 @@ class DoxygenMethodDocumenter(DoxygenDocumenter): if '::' in self.fullname: (obj, meth) = self.fullname.rsplit('::', 1) - prefix = './/compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]'.format(obj) + # '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 @@ -389,7 +407,7 @@ class DoxygenMethodDocumenter(DoxygenDocumenter): xpath_query_noparam = ('{:s}/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(prefix, meth) xpath_query = "" - if self.argsstring != None: + 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 @@ -397,23 +415,25 @@ class DoxygenMethodDocumenter(DoxygenDocumenter): if not match: logger = logging.getLogger(__name__) - if self.argsstring != None: + 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)) + .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)") 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)) + 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): + 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 @@ -437,7 +457,8 @@ class DoxygenMethodDocumenter(DoxygenDocumenter): rtype = rtype_el.text # print("rtype: {}".format(rtype)) - signame = (rtype and (rtype + ' ') or '') + self.klassname + "::"+ self.objname + 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): @@ -449,7 +470,8 @@ class DoxygenMethodDocumenter(DoxygenDocumenter): return ret def format_signature(self): - args = self.object.find('argsstring').text + args = fix_namespaces(self.object.find('argsstring').text) +# print ("signature: {}".format(args)) return args def document_members(self, all_members=False): @@ -517,11 +539,11 @@ class DoxygenVariableDocumenter(DoxygenDocumenter): else: rtype = rtype_el.text - # print("rtype: {}".format(rtype)) +# print("rtype: {}".format(rtype)) signame = (rtype and (rtype + ' ') or '') + self.klassname + "::" + self.objname - return self.format_template_name() + signame + return fix_namespaces(self.format_template_name() + signame) - def get_doc(self, encoding): + 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 @@ -564,6 +586,9 @@ def set_doxygen_xml(app): 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. @@ -586,6 +611,7 @@ def setup(app): 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)