X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/blobdiff_plain/50e3c4f71ed71c12df72d5874c7b7c92d71496aa..466f188952918914db8c4124caa1b196cef505be:/docs/source/_ext/autodoxy.py diff --git a/docs/source/_ext/autodoxy.py b/docs/source/_ext/autodoxy.py index 00720cb7f2..0a854cabd5 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 @@ -130,7 +135,7 @@ class _DoxygenXmlParagraphFormatter(object): self.continue_line = True def visit_parameterlist(self, node): - lines = [l for l in type(self)().generic_visit(node).lines if l is not ''] + 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): @@ -191,12 +196,12 @@ class DoxygenDocumenter(Documenter): 'members': members_option, } - def __init__(self, directive, name, indent=u'', id=None): + def __init__(self, directive, name, indent=u'', my_id = None): super(DoxygenDocumenter, self).__init__(directive, name, indent) - if id is not None: - self.parse_id(id) + if my_id is not None: + self.parse_id(my_id) - def parse_id(self, id): + def parse_id(self, id_to_parse): return False def parse_name(self): @@ -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' @@ -360,8 +377,8 @@ class DoxygenMethodDocumenter(DoxygenDocumenter): return True return False - def parse_id(self, id): - xp = './/*[@id="%s"]' % id + def parse_id(self, id_to_parse): + xp = './/*[@id="%s"]' % id_to_parse match = get_doxygen_root().xpath(xp) if match: match = match[0] @@ -378,38 +395,45 @@ class DoxygenMethodDocumenter(DoxygenDocumenter): # classname or method name return True - (obj, meth) = self.fullname.rsplit('::', 1) + 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 = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]' - '/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(obj, meth) + xpath_query_noparam = ('{:s}/memberdef[@kind="function"]/name[text()="{:s}"]/..').format(prefix, meth) xpath_query = "" -# print("fullname {}".format(self.fullname)) - if self.argsstring != None: - xpath_query = ('.//compoundname[text()="{:s}"]/../sectiondef[@kind="public-func" or @kind="public-static-func"]' - '/memberdef[@kind="function" and argsstring/text()="{:s}"]/name[text()="{:s}"]/..').format(obj,self.argsstring,meth) + 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 != 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)) + 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)) + 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)) + 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".format(obj, meth)) + 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 @@ -433,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): @@ -445,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): @@ -484,8 +510,8 @@ class DoxygenVariableDocumenter(DoxygenDocumenter): self.object = match[0] return True - def parse_id(self, id): - xp = './/*[@id="%s"]' % id + def parse_id(self, id_to_parse): + xp = './/*[@id="%s"]' % id_to_parse match = get_doxygen_root().xpath(xp) if match: match = match[0] @@ -510,16 +536,20 @@ class DoxygenVariableDocumenter(DoxygenDocumenter): 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) +# print(" --> rtype_el: {} rtype_el_ref: {}".format(text(rtype_el), text(rtype_el_ref))) 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 + res = fix_namespaces(self.format_template_name() + signame) +# print("formatted name: {}".format(res)) + return res - 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)] +# print ("doc: {}".format(doc)) return doc def format_template_name(self): @@ -555,11 +585,14 @@ def set_doxygen_xml(app): raise err setup.DOXYGEN_ROOT = ET.ElementTree(ET.Element('root')).getroot() - for file in files: - root = ET.parse(file).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. @@ -582,6 +615,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)