Fix a few broken references and other warnings in the doc

[simgrid.git] / docs / source / _ext / autodoxy.py

diff --git a/docs/source/_ext/autodoxy.py b/docs/source/_ext/autodoxy.py
index d5ccfd5..0a854ca 100644 (file)
--- a/docs/source/_ext/autodoxy.py
+++ b/docs/source/_ext/autodoxy.py
@@ -358,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'
@@ -400,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
@@ -408,7 +415,7 @@ 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."
@@ -450,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):
@@ -462,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):
@@ -527,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=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):
@@ -577,6 +590,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.
@@ -599,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)