Doxygen test also checks for broken 'see also' links

qgis · May 25, 2018 · fa912f5 · fa912f5
1 parent 1d8689f
commit fa912f5
Show file tree

Hide file tree

Showing 2 changed files with 35 additions and 2 deletions.
diff --git a/tests/code_layout/doxygen_parser.py b/tests/code_layout/doxygen_parser.py
@@ -53,6 +53,7 @@ def __init__(self, path, acceptable_missing={}, acceptable_missing_added_note=[]
         self.documented_members = 0
         self.undocumented_members = {}
         self.noncompliant_members = {}
+        self.broken_links = {}
         self.bindable_members = []
         self.groups = {}
         self.classes_missing_group = []
@@ -141,7 +142,7 @@ def parseFile(self, f):
                 if event == 'end' and elem.tag == 'compounddef':
                     if self.elemIsPublicClass(elem):
                         # store documentation status
-                        members, documented, undocumented, noncompliant, bindable, has_brief_description, found_version_added = self.parseClassElem(elem)
+                        members, documented, undocumented, noncompliant, bindable, has_brief_description, found_version_added, broken_links = self.parseClassElem(elem)
                         documentable_members += members
                         documented_members += documented
                         class_name = elem.find('compoundname').text
@@ -172,6 +173,9 @@ def parseFile(self, f):
                         if len(noncompliant) > 0:
                             self.noncompliant_members[class_name] = noncompliant
 
+                        if broken_links:
+                            self.broken_links[class_name] = broken_links
+
                         # store bindable members
                         if self.classElemIsBindable(elem):
                             for m in bindable:
@@ -230,6 +234,7 @@ def parseClassElem(self, e):
         undocumented_members = set()
         noncompliant_members = []
         bindable_members = []
+        broken_links = {}
         # loop through all members
         for m in e.getiterator('memberdef'):
             signature = self.memberSignature(m)
@@ -248,6 +253,11 @@ def parseClassElem(self, e):
                         noncompliant_members.append({m.find('name').text: error})
                 else:
                     undocumented_members.add(signature)
+
+                broken_see_also_links = self.checkForBrokenSeeAlsoLinks(m)
+                if broken_see_also_links:
+                    broken_links[m.find('name').text] = broken_see_also_links
+
         # test for brief description
         d = e.find('briefdescription')
         has_brief_description = False
@@ -267,7 +277,7 @@ def parseClassElem(self, e):
             if found_version_added:
                 break
 
-        return documentable_members, documented_members, undocumented_members, noncompliant_members, bindable_members, has_brief_description, found_version_added
+        return documentable_members, documented_members, undocumented_members, noncompliant_members, bindable_members, has_brief_description, found_version_added, broken_links
 
     def memberSignature(self, elem):
         """ Returns the signature for a member
@@ -565,3 +575,20 @@ def memberDocIsNonCompliant(self, member_elem):
                     #elif para.text.strip().lower().startswith('set '):
                     #    return 'Use "Sets the..." instead of "set ..."'
         return False
+
+    def checkForBrokenSeeAlsoLinks(self, elem):
+        """
+        Checks for any broken 'see also' links
+        """
+        broken = []
+        detailed_sec = elem.find('detaileddescription')
+        for p in detailed_sec.getiterator('para'):
+            for s in p.getiterator('simplesect'):
+                if s.get('kind') != 'see':
+                    continue
+
+                para = s.getchildren()[0]
+                if para.find('ref') is None and para.text:
+                    broken.append(para.text)
+
+        return broken
diff --git a/tests/code_layout/test_qgsdoccoverage.py b/tests/code_layout/test_qgsdoccoverage.py
@@ -67,6 +67,12 @@ def testCoverage(self):
                     for mem, error in p.items():
                         print((colored('  ' + mem + ': ' + error, 'yellow', attrs=['bold'])))
 
+        if parser.broken_links:
+            for cls, props in list(parser.broken_links.items()):
+                print(('\n\nClass {}, broken see also links found\n'.format(colored(cls, 'yellow'))))
+                for member, links in props.items():
+                    for l in links:
+                        print((colored('  ' + member + ': ' + l, 'yellow', attrs=['bold'])))
         # self.assertEquals(len(parser.undocumented_string), 0, 'FAIL: new undocumented members have been introduced, please add documentation for these members')
 
         if parser.classes_missing_group: