From 7e4525e27a4e0301c932382555fa0b2cd563302c Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 14 Sep 2020 00:38:58 +0200 Subject: [PATCH] autodoxy: allow to requalify types whose namespace is implicit in doxygen This is somewhat hackish, as it's a RE substitution, but it's doing the trick so far. --- docs/Build.sh | 5 +---- docs/source/_ext/autodoxy.py | 19 ++++++++++++++++--- docs/source/conf.py | 32 +++++++++++++++++++++++++++++++- 3 files changed, 48 insertions(+), 8 deletions(-) diff --git a/docs/Build.sh b/docs/Build.sh index b057c009d2..cc536cb689 100755 --- a/docs/Build.sh +++ b/docs/Build.sh @@ -44,10 +44,7 @@ EOF echo "javasphinx relaunched" fi -PYTHONPATH=../lib:source/_ext/javasphinx sphinx-build -M html source build ${SPHINXOPTS} 2>&1 \ - | grep -v 'WARNING: cpp:identifier reference target not found: simgrid$' \ - | grep -v 'WARNING: cpp:identifier reference target not found: simgrid::s4u$' \ - | grep -v 'WARNING: cpp:identifier reference target not found: boost' +PYTHONPATH=../lib:source/_ext/javasphinx sphinx-build -M html source build ${SPHINXOPTS} 2>&1 set +x diff --git a/docs/source/_ext/autodoxy.py b/docs/source/_ext/autodoxy.py index d5ccfd59cd..5811d2af70 100644 --- 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' @@ -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): @@ -532,7 +541,7 @@ class DoxygenVariableDocumenter(DoxygenDocumenter): # 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=None): # This method is called with 1 parameter in Sphinx 2.x and 2 parameters in Sphinx 1.x detaileddescription = self.object.find('detaileddescription') @@ -577,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. @@ -599,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) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0ca9461b26..d931437de3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -67,6 +67,37 @@ breathe_default_project = "simgrid" # Setup the autodoxy extension doxygen_xml = os.path.join(os.path.dirname(__file__), "..", "build", "xml") +autodoxy_requalified_identifiers = [ # The first element will be substituted into the second one if it's starting an element or preceded by a space + ("ActorPtr", "simgrid::s4u::ActorPtr"), + ("Actor", "simgrid::s4u::Actor"), + ("CommPtr", "simgrid::s4u::CommPtr"), + ("Disk", "simgrid::s4u::Disk"), + ("ExecPtr", "simgrid::s4u::ExecPtr"), + ("Host", "simgrid::s4u::Host"), + ("s4u::Host", "simgrid::s4u::Host"), + ("Engine", "simgrid::s4u::Engine"), + ("Link", "simgrid::s4u::Link"), + ("Mailbox", "simgrid::s4u::Mailbox"), + ("Mutex", "simgrid::s4u::Mutex"), + ("s4u::Mutex", "simgrid::s4u::Mutex"), + ("NetZone", "simgrid::s4u::NetZone"), + ("Semaphore", "simgrid::s4u::Semaphore"), + ] + +# Generate a warning for all a cross-reference (such as :func:`myfunc`) that cannot be found +nitpicky = True +nitpick_ignore = [ + ('cpp:identifier', 'boost'), + ('cpp:identifier', 'kernel'), + ('cpp:identifier', 'simgrid'), + ('cpp:identifier', 'simgrid::s4u'), + ('cpp:identifier', 'this_actor'), + ('cpp:identifier', 's4u'), + ('cpp:identifier', 'size_t'), + ('cpp:identifier', 'uint64_t'), + ('cpp:identifier', 'xbt'), + ('cpp:identifier', 'xbt::string'), +] # For cross-ref generation primary_domain = 'cpp' @@ -151,4 +182,3 @@ html_css_files = [ # -- Other options -nitpicky = True # Generate a warning for all a cross-reference (such as :func:`myfunc`) that cannot be found -- 2.20.1