#! /usr/bin/env python3
# -*- coding: utf-8 -*-
-# Copyright (c) 2019-2021. The SimGrid Team. All rights reserved.
+# Copyright (c) 2019-2023. The SimGrid Team. All rights reserved.
# This program is free software; you can redistribute it and/or modify it
# under the terms of the license (GNU LGPL) which comes with this package.
"""
Search for symbols documented in both the XML files produced by Doxygen and the python modules,
-but not documented with autodoxy in the RST files.
+but not documented with breathe in the RST files.
-This script is tailored to SimGrid own needs and should be made more generic for autodoxy.
+This script is tailored to SimGrid own needs.
If you are missing some dependencies, try: pip3 install --requirement docs/requirements.txt
"""
-import fnmatch
import os
import re
import sys
'build/xml/host_8h.xml',
'build/xml/link_8h.xml',
'build/xml/mailbox_8h.xml',
- 'build/xml/msg_8h.xml',
'build/xml/mutex_8h.xml',
'build/xml/semaphore_8h.xml',
'build/xml/vm_8h.xml',
if fullname in python_ignore:
- print ("Ignore Python symbol '{}' as requested.".format(fullname))
+ print("Ignore Python symbol '{}' as requested.".format(fullname))
return
if inspect.isroutine(elm) and inspect.isclass(englobing):
elif inspect.isdatadescriptor(elm):
found_decl("attribute", fullname)
# print('.. autoattribute:: {}'.format(fullname))
- elif isinstance(elm, str) or isinstance(elm, int): # We do have such a data, directly in the SimGrid top module
+ elif isinstance(elm, (int, str)): # We do have such a data, directly in the SimGrid top module
found_decl("data", fullname)
# print('.. autodata:: {}'.format(fullname))
+ elif inspect.isclass(type(elm)): # Enum classes are of that kind
+ found_decl("data", fullname)
+ #print('.. autodata:: {}'.format(fullname))
elif inspect.ismodule(elm) or inspect.isclass(elm):
for name, data in inspect.getmembers(elm):
if name.startswith('__'):
# print("Recurse on {}.{}".format(fullname, name))
handle_python_module("{}.{}".format(fullname, name), elm, data)
else:
- print('UNHANDLED TYPE {} : {!r} Type: {}'.format(fullname, elm, type(elm)))
+ print('UNHANDLED TYPE {} : {!r} Type: {} Englobing: {} str: {} Members: \n{}\n'.format(fullname, elm, type(elm), englobing, str(elm), inspect.getmembers(elm)))
# Start the recursion on the provided Python modules
for name in python_modules:
doxy_funs = {} # {classname: {func_name: [args]} }
doxy_vars = {} # {classname: [names]}
+doxy_type = {} # {classname: [names]}
# find the declarations in the XML files
for arg in xml_files:
if arg[-4:] != '.xml':
- print ("Argument '{}' does not end with '.xml'".format(arg))
+ print("Argument '{}' does not end with '.xml'".format(arg))
continue
#print("Parse file {}".format(arg))
tree = ET.parse(arg)
if "compoundname" in elem:
raise Exception("Compound {} has no 'compoundname' child tag.".format(elem))
compoundname = elem.find("compoundname").text
- #print ("compoundname {}".format(compoundname))
+ #print("compoundname {}".format(compoundname))
elif elem.attrib["kind"] == "file":
compoundname = ""
elif elem.attrib["kind"] == "namespace":
doxy_vars[compoundname].append(name)
elif kind == "function":
args = member.find('argsstring').text
- args = re.sub('\)[^)]*$', ')', args) # ignore what's after the parameters (eg, '=0' or ' const')
+ args = re.sub(r'\)[^)]*$', ')', args) # ignore what's after the parameters (eg, '=0' or ' const')
if compoundname not in doxy_funs:
doxy_funs[compoundname] = {}
if name not in doxy_funs[compoundname]:
doxy_funs[compoundname][name] = []
doxy_funs[compoundname][name].append(args)
+ elif kind == "typedef":
+ if compoundname not in doxy_type:
+ doxy_type[compoundname] = []
+ doxy_type[compoundname].append(name)
elif kind == "friend":
pass # Ignore friendship
else:
- print ("member {}::{} is of kind {}".format(compoundname, name, kind))
+ print("member {}::{} is of kind {}".format(compoundname, name, kind))
# Forget about the declarations that are done in the RST
-with os.popen('grep doxygenfunction:: find-missing.ignore source/*rst|sed \'s/^.*doxygenfunction:: //\'') as pse:
+with os.popen('grep doxygenfunction:: find-missing.ignore source/*rst|sed \'s/^.*doxygenfunction:: //\'|sed \'s/ *const//\'') as pse:
for line in (l.strip() for l in pse):
(klass, obj, args) = (None, None, None)
if "(" in line:
print("Warning: Object '{}' documented but not found in '{}'".format(line, klass))
# for obj in doxy_funs[klass]:
# print(" found: {}::{}".format(klass, obj))
- elif len(doxy_funs[klass][obj])==1:
+ elif len(doxy_funs[klass][obj]) == 1:
del doxy_funs[klass][obj]
elif args not in doxy_funs[klass][obj]:
print("Warning: Function {}{} not found in {}".format(obj, args, klass))
doxy_funs[klass][obj].remove(args)
if len(doxy_funs[klass][obj]) == 0:
del doxy_funs[klass][obj]
-with os.popen('grep autodoxyvar:: find-missing.ignore source/*rst|sed \'s/^.*autodoxyvar:: //\'') as pse:
+with os.popen('grep doxygenvariable:: find-missing.ignore source/*rst|sed \'s/^.*doxygenvariable:: //\'') as pse:
for line in (l.strip() for l in pse):
(klass, var) = line.rsplit('::', 1)
print("Warning: {} documented, but class {} not found in doxygen.".format(line, klass))
continue
if var not in doxy_vars[klass]:
- print("Warning: Object {} documented but not found in {}".format(line, klass))
+ print("Warning: Object {} documented but not found in '{}'".format(line, klass))
else:
# print("Found {} in {}".format(line, klass))
doxy_vars[klass].remove(var)
if len(doxy_vars[klass]) == 0:
del doxy_vars[klass]
+with os.popen('grep doxygentypedef:: find-missing.ignore source/*rst|sed \'s/^.*doxygentypedef:: //\'') as pse:
+ for line in (l.strip() for l in pse):
+ if '::' in line:
+ (klass, typ) = line.rsplit('::', 1)
+ else:
+ (klass, typ) = ('', line)
+
+ if klass not in doxy_type:
+ print("Warning: {} documented, but class {} not found in doxygen.".format(line, klass))
+ continue
+ if typ not in doxy_type[klass]:
+ print("Warning: Type {} documented but not found in '{}'".format(line, klass))
+ else:
+# print("Found {} in {}".format(line, klass))
+ doxy_type[klass].remove(typ)
+ if len(doxy_type[klass]) == 0:
+ del doxy_type[klass]
-# Dump the undocumented Doxygen declarations
+# Dump the undocumented Doxygen declarations
for obj in sorted(doxy_funs):
for meth in sorted(doxy_funs[obj]):
for args in sorted(doxy_funs[obj][meth]):
- print(".. doxygenfunction:: {}::{}{}".format(obj, meth, args))
+ if obj == '':
+ print(".. doxygenfunction:: {}{}".format(meth, args))
+ else:
+ print(".. doxygenfunction:: {}::{}{}".format(obj, meth, args))
for obj in doxy_vars:
for meth in sorted(doxy_vars[obj]):
- print(".. autodoxyvar:: {}::{}".format(obj, meth))
+ print(".. doxygenvariable:: {}::{}".format(obj, meth))
+
+for obj in doxy_type:
+ for meth in sorted(doxy_type[obj]):
+ if obj == '':
+ print(".. doxygentypedef:: {}".format(meth))
+ else:
+ print(".. doxygentypedef:: {}::{}".format(obj, meth))