documentation/doxygen: "improve" empty page filtering.

By throwing more mud at the wall. Ugh. Wow doxygen, why is everything
so damn hard.

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index c12a54fc26e3ad30bd810ccbf071225712bed5f4..e2d96796e2b6e115b43019ae2f9c650855f2bcdc 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -2339,6 +2339,18 @@ def _document_all_stuff(compounddef: ET.Element):
             para.append(dim)
             brief.append(para)
 
+def is_a_stupid_empty_markdown_page(compounddef: ET.Element):
+    assert compounddef.attrib['kind'] == 'page'
+
+    # Doxygen creates a page for *all* markdown files even thought they
+    # otherwise contain absolutely NOTHING except for symbol documentation.
+    # And of course it's nearly impossible to distinguish those unwanted pages
+    # from actually wanted (but empty) pages so at least I'm filtering out
+    # everything that starts with md_ and ends with the same thing as the title
+    # (which means there's no explicit title). We *do* want to preserve empty
+    # pages with custom titles.
+    return compounddef.find('compoundname').text.startswith('md_') and compounddef.find('compoundname').text.endswith(compounddef.find('title').text) and not compounddef.find('briefdescription') and not compounddef.find('detaileddescription')
+
 def extract_metadata(state: State, xml):
     logging.debug("Extracting metadata from {}".format(os.path.basename(xml)))
 
@@ -2385,8 +2397,9 @@ def extract_metadata(state: State, xml):
     compound.url = 'index.html' if compound.kind == 'page' and compound.id == 'indexpage' else compound.id + '.html'
     compound.brief = parse_desc(state, compounddef.find('briefdescription'))
     # Groups are explicitly created so they *have details*, other
-    # things need to have at least some documentation
-    compound.has_details = compound.kind == 'group' or compound.brief or compounddef.find('detaileddescription')
+    # things need to have at least some documentation. Pages are treated as
+    # having something unless they're stupid. See the function for details.
+    compound.has_details = compound.kind == 'group' or compound.brief or compounddef.find('detaileddescription') or (compound.kind == 'page' and not is_a_stupid_empty_markdown_page(compounddef))
     compound.children = []
 
     # Deprecation status
@@ -2685,8 +2698,9 @@ def parse_xml(state: State, xml: str):
         _document_all_stuff(compounddef)
 
     # Ignoring compounds w/o any description, except for groups,
-    # which are created explicitly
-    if not compounddef.find('briefdescription') and not compounddef.find('detaileddescription') and not compounddef.attrib['kind'] == 'group':
+    # which are created explicitly. Pages are treated as having something
+    # unless they're stupid. See the function for details.
+    if not compounddef.find('briefdescription') and not compounddef.find('detaileddescription') and not compounddef.attrib['kind'] == 'group' and (not compounddef.attrib['kind'] == 'page' or is_a_stupid_empty_markdown_page(compounddef)):
         logging.debug("{}: neither brief nor detailed description present, skipping".format(state.current))
         return None
 

diff --git a/documentation/test_doxygen/page_empty_page/Doxyfile b/documentation/test_doxygen/page_empty_page/Doxyfile
index 7c1670c1f2f9831fd1ded5cd862e1708af730656..f1fc665f95d6134989448d53fb06d17fc66eb249 100644 (file)
--- a/documentation/test_doxygen/page_empty_page/Doxyfile
+++ b/documentation/test_doxygen/page_empty_page/Doxyfile
@@ -1,4 +1,4 @@
-INPUT                   = input.h input.md
+INPUT                   = input.h input.md subdir/otherinput.md
 QUIET                   = YES
 GENERATE_HTML           = NO
 GENERATE_LATEX          = NO

diff --git a/documentation/test_doxygen/page_empty_page/subdir/otherinput.md b/documentation/test_doxygen/page_empty_page/subdir/otherinput.md
new file mode 100644 (file)
index 0000000..8b13789
--- /dev/null
+++ b/documentation/test_doxygen/page_empty_page/subdir/otherinput.md
@@ -0,0 +1 @@
+

diff --git a/documentation/test_doxygen/test_page.py b/documentation/test_doxygen/test_page.py
index fdee57ea86d8c2fb25c1fafdf858a11ebf3adbee..8fb9cd760e07c1305f5402e3880744a05fe66bd6 100644 (file)
--- a/documentation/test_doxygen/test_page.py
+++ b/documentation/test_doxygen/test_page.py
@@ -109,4 +109,5 @@ class EmptyPage(IntegrationTestCase):
     def test(self):
         self.run_doxygen(wildcard='*.xml')
         self.assertFalse(os.path.exists(os.path.join(self.path, 'html', 'group__bla_md_input.html')))
+        self.assertFalse(os.path.exists(os.path.join(self.path, 'html', 'md_subdir_otherinput.html')))
         self.assertEqual(*self.actual_expected_contents('pages.html'))