From 901676ac12e759b430f5fb86892635adac7832c8 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Sun, 7 Jul 2019 15:05:33 +0200
Subject: [PATCH] documentation/doxygen: "improve" empty page filtering.

By throwing more mud at the wall. Ugh. Wow doxygen, why is everything
so damn hard.
---
 documentation/doxygen.py                      | 22 +++++++++++++++----
 .../test_doxygen/page_empty_page/Doxyfile     |  2 +-
 .../page_empty_page/subdir/otherinput.md      |  1 +
 documentation/test_doxygen/test_page.py       |  1 +
 4 files changed, 21 insertions(+), 5 deletions(-)
 create mode 100644 documentation/test_doxygen/page_empty_page/subdir/otherinput.md

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index c12a54fc..e2d96796 100755
--- 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 7c1670c1..f1fc665f 100644
--- 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
index 00000000..8b137891
--- /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 fdee57ea..8fb9cd76 100644
--- 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'))
-- 
2.30.2