chiark / gitweb /
documentation/doxygen: work around Doxyen stupidly making XMLs useless.
authorVladimír Vondruš <mosra@centrum.cz>
Sat, 14 Sep 2024 02:08:57 +0000 (04:08 +0200)
committerVladimír Vondruš <mosra@centrum.cz>
Sat, 14 Sep 2024 03:06:20 +0000 (05:06 +0200)
I still hope that particular change can be reverted, but so far it's
just the least possible amount of work to make this tool not hit a
sanity assert.

documentation/doxygen.py
documentation/test_doxygen/compound_includes/namespaceContained-stupid.html [new file with mode: 0644]
documentation/test_doxygen/compound_includes_disabled/namespaceContained-stupid.html [new file with mode: 0644]
documentation/test_doxygen/compound_modules_in_namespace/file3_8h-stupid.html [new file with mode: 0644]
documentation/test_doxygen/compound_modules_in_namespace/namespaceNamespace-stupid.html [new file with mode: 0644]
documentation/test_doxygen/contents_anchor_in_both_group_and_namespace/namespaceFoo-stupid.html [new file with mode: 0644]
documentation/test_doxygen/test_compound.py
documentation/test_doxygen/test_contents.py
documentation/test_doxygen/test_undocumented.py
documentation/test_doxygen/undocumented/File_8h-stupid.html [new file with mode: 0644]
documentation/test_doxygen/undocumented/namespaceNamespace-stupid.html [new file with mode: 0644]

index d2f4956e4133e35d0e520b5668443874d56a9408..a4612ff70f882cc4708c1585887a6e1f963efdb3 100755 (executable)
@@ -3020,6 +3020,33 @@ def parse_xml(state: State, xml: str):
 
         # Other, grouped in sections
         elif compounddef_child.tag == 'sectiondef':
+            # If grouping is used in the documentation, Doxygen 1.9.7+ no
+            # longer puts the whole <memberdef> info into file and namespace
+            # docs, but instead only <member> references, forcing the parsers
+            # to look for the identifier in other XML files.
+            #
+            # The reason for this, as discussed in the linked PR, is because
+            # some random downstream project failed due to encountering
+            # duplicate IDs (which are there for file/namespace members also,
+            # by the way! or for relatedalso members!!). And Doxygen maintainer
+            # VERY HELPFULLY OFFERED TO CRIPPLE THE XML OUTPUT FOR EVERYONE
+            # ELSE just to fix that damn thing. Once I calm down I may try to
+            # convince them to revert this insanity, until then enjoy the
+            # crappy output.
+            #
+            # Also, yes, it may happen that there are combined <memberdef> and
+            # <member> children. But handling that means adding the same damn
+            # piece of code, or some dumb filtering, to all branches below,
+            # just to counter a dumb decision. Nope. Nononono.
+            is_stupid = False
+            for memberdef in compounddef_child:
+                if memberdef.tag == 'member':
+                    logging.warning("{}: sorry, parsing of non-self-contained XML not implemented: due to https://github.com/doxygen/doxygen/issues/8790 the output will not list file / namespace {} members".format(state.current, compounddef_child.attrib['kind']))
+                    is_stupid = True
+                    break
+            if is_stupid:
+                continue
+
             if compounddef_child.attrib['kind'] == 'enum':
                 for memberdef in compounddef_child:
                     enum = parse_enum(state, memberdef)
diff --git a/documentation/test_doxygen/compound_includes/namespaceContained-stupid.html b/documentation/test_doxygen/compound_includes/namespaceContained-stupid.html
new file mode 100644 (file)
index 0000000..01d6b3a
--- /dev/null
@@ -0,0 +1,105 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Contained namespace | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          Contained <span class="m-thin">namespace</span>
+          <div class="m-doc-include m-code m-inverted m-text-right"><span class="cp">#include</span> <a class="cpf" href="First_8h.html">&lt;First.h&gt;</a></div>
+        </h1>
+        <p>This namespace is contained in a single file.</p>
+        <nav class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#enum-members">Enums</a></li>
+                <li><a href="#typedef-members">Typedefs</a></li>
+                <li><a href="#func-members">Functions</a></li>
+                <li><a href="#var-members">Variables</a></li>
+                <li><a href="#a-group">A group</a></li>
+              </ul>
+            </li>
+          </ul>
+        </nav>
+<p>So it has only the global include and no per-entry includes, thus also no detailed sections because there&#x27;s only brief. (Unless the includes are disabled globally or the file is not documented.)</p>
+        <section id="enum-members">
+          <h2><a href="#enum-members">Enums</a></h2>
+          <dl class="m-doc">
+            <dt id="a1e198a456efa4fe54dfc7f1f60e0b5d7">
+              <span class="m-doc-wrap-bumper">enum <a href="#a1e198a456efa4fe54dfc7f1f60e0b5d7" class="m-doc-self">Enum</a> { </span><span class="m-doc-wrap"> }</span>
+            </dt>
+            <dd>An enum.</dd>
+          </dl>
+        </section>
+        <section id="typedef-members">
+          <h2><a href="#typedef-members">Typedefs</a></h2>
+          <dl class="m-doc">
+            <dt id="a011bc16d926b77ad9f172540494d8e84">
+              using <a href="#a011bc16d926b77ad9f172540494d8e84" class="m-doc-self">Int1</a> = int
+            </dt>
+            <dd>A typedef.</dd>
+          </dl>
+        </section>
+        <section id="func-members">
+          <h2><a href="#func-members">Functions</a></h2>
+          <dl class="m-doc">
+            <dt id="a805f49495092c6f2bb1347f50bf2453e">
+              <span class="m-doc-wrap-bumper">void <a href="#a805f49495092c6f2bb1347f50bf2453e" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd>A function.</dd>
+          </dl>
+        </section>
+        <section id="var-members">
+          <h2><a href="#var-members">Variables</a></h2>
+          <dl class="m-doc">
+            <dt id="a91e894fe69f4a6c73074f7862ede5503">
+              const int <a href="#a91e894fe69f4a6c73074f7862ede5503" class="m-doc-self">Var</a> <span class="m-label m-flat m-primary">constexpr</span>
+            </dt>
+            <dd>A variable.</dd>
+          </dl>
+        </section>
+        <section id="a-group">
+          <h2><a href="#a-group">A group</a></h2>
+          <dl class="m-doc">
+            <dt id="a11d588fad4de0640556b055558c5fa1d">
+              <span class="m-doc-wrap-bumper">enum <a href="#a11d588fad4de0640556b055558c5fa1d" class="m-doc-self">Flag</a> { </span><span class="m-doc-wrap"> }</span>
+            </dt>
+            <dd>Flag in a group.</dd>
+            <dt id="ad769587e750dd7cd8de308987f7ccf30">
+              using <a href="#ad769587e750dd7cd8de308987f7ccf30" class="m-doc-self">Main</a> = void
+            </dt>
+            <dd>Alias in a group.</dd>
+            <dt id="ac65f93520b7abe37daa15a999faa4323">
+              void* <a href="#ac65f93520b7abe37daa15a999faa4323" class="m-doc-self">variable</a> <span class="m-label m-flat m-primary">constexpr</span>
+            </dt>
+            <dd>Variable in a group.</dd>
+            <dt id="abcad26bce92bd85654aaf9b7effc043b">
+              <span class="m-doc-wrap-bumper">void <a href="#abcad26bce92bd85654aaf9b7effc043b" class="m-doc-self">bar</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd>Function in a group.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_doxygen/compound_includes_disabled/namespaceContained-stupid.html b/documentation/test_doxygen/compound_includes_disabled/namespaceContained-stupid.html
new file mode 100644 (file)
index 0000000..044aeb3
--- /dev/null
@@ -0,0 +1,104 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Contained namespace | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          Contained <span class="m-thin">namespace</span>
+        </h1>
+        <p>This namespace is contained in a single file.</p>
+        <nav class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#enum-members">Enums</a></li>
+                <li><a href="#typedef-members">Typedefs</a></li>
+                <li><a href="#func-members">Functions</a></li>
+                <li><a href="#var-members">Variables</a></li>
+                <li><a href="#a-group">A group</a></li>
+              </ul>
+            </li>
+          </ul>
+        </nav>
+<p>So it has only the global include and no per-entry includes, thus also no detailed sections because there&#x27;s only brief. (Unless the includes are disabled globally or the file is not documented.)</p>
+        <section id="enum-members">
+          <h2><a href="#enum-members">Enums</a></h2>
+          <dl class="m-doc">
+            <dt id="a1e198a456efa4fe54dfc7f1f60e0b5d7">
+              <span class="m-doc-wrap-bumper">enum <a href="#a1e198a456efa4fe54dfc7f1f60e0b5d7" class="m-doc-self">Enum</a> { </span><span class="m-doc-wrap"> }</span>
+            </dt>
+            <dd>An enum.</dd>
+          </dl>
+        </section>
+        <section id="typedef-members">
+          <h2><a href="#typedef-members">Typedefs</a></h2>
+          <dl class="m-doc">
+            <dt id="a011bc16d926b77ad9f172540494d8e84">
+              using <a href="#a011bc16d926b77ad9f172540494d8e84" class="m-doc-self">Int1</a> = int
+            </dt>
+            <dd>A typedef.</dd>
+          </dl>
+        </section>
+        <section id="func-members">
+          <h2><a href="#func-members">Functions</a></h2>
+          <dl class="m-doc">
+            <dt id="a805f49495092c6f2bb1347f50bf2453e">
+              <span class="m-doc-wrap-bumper">void <a href="#a805f49495092c6f2bb1347f50bf2453e" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd>A function.</dd>
+          </dl>
+        </section>
+        <section id="var-members">
+          <h2><a href="#var-members">Variables</a></h2>
+          <dl class="m-doc">
+            <dt id="a91e894fe69f4a6c73074f7862ede5503">
+              const int <a href="#a91e894fe69f4a6c73074f7862ede5503" class="m-doc-self">Var</a> <span class="m-label m-flat m-primary">constexpr</span>
+            </dt>
+            <dd>A variable.</dd>
+          </dl>
+        </section>
+        <section id="a-group">
+          <h2><a href="#a-group">A group</a></h2>
+          <dl class="m-doc">
+            <dt id="a11d588fad4de0640556b055558c5fa1d">
+              <span class="m-doc-wrap-bumper">enum <a href="#a11d588fad4de0640556b055558c5fa1d" class="m-doc-self">Flag</a> { </span><span class="m-doc-wrap"> }</span>
+            </dt>
+            <dd>Flag in a group.</dd>
+            <dt id="ad769587e750dd7cd8de308987f7ccf30">
+              using <a href="#ad769587e750dd7cd8de308987f7ccf30" class="m-doc-self">Main</a> = void
+            </dt>
+            <dd>Alias in a group.</dd>
+            <dt id="ac65f93520b7abe37daa15a999faa4323">
+              void* <a href="#ac65f93520b7abe37daa15a999faa4323" class="m-doc-self">variable</a> <span class="m-label m-flat m-primary">constexpr</span>
+            </dt>
+            <dd>Variable in a group.</dd>
+            <dt id="abcad26bce92bd85654aaf9b7effc043b">
+              <span class="m-doc-wrap-bumper">void <a href="#abcad26bce92bd85654aaf9b7effc043b" class="m-doc-self">bar</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd>Function in a group.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_doxygen/compound_modules_in_namespace/file3_8h-stupid.html b/documentation/test_doxygen/compound_modules_in_namespace/file3_8h-stupid.html
new file mode 100644 (file)
index 0000000..11a3fc9
--- /dev/null
@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>file3.h file | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          file3.h <span class="m-thin">file</span>
+        </h1>
+        <p>Include file with some stuff that belongs to group 1 and group 2.</p>
+        <nav class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#namespaces">Namespaces</a></li>
+              </ul>
+            </li>
+          </ul>
+        </nav>
+        <section id="namespaces">
+          <h2><a href="#namespaces">Namespaces</a></h2>
+          <dl class="m-doc">
+            <dt>namespace <a href="namespaceNamespace.html" class="m-doc">Namespace</a></dt>
+            <dd>A namespace.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_doxygen/compound_modules_in_namespace/namespaceNamespace-stupid.html b/documentation/test_doxygen/compound_modules_in_namespace/namespaceNamespace-stupid.html
new file mode 100644 (file)
index 0000000..3f1d12a
--- /dev/null
@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Namespace namespace | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          Namespace <span class="m-thin">namespace</span>
+        </h1>
+        <p>A namespace.</p>
+<p>This is a namespace. It is spread across two files.</p>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_doxygen/contents_anchor_in_both_group_and_namespace/namespaceFoo-stupid.html b/documentation/test_doxygen/contents_anchor_in_both_group_and_namespace/namespaceFoo-stupid.html
new file mode 100644 (file)
index 0000000..aa4dd52
--- /dev/null
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Foo namespace | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          Foo <span class="m-thin">namespace</span>
+        </h1>
+        <p><a href="namespaceFoo.html" class="m-doc">Foo</a>.</p>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
index 4c8d5302725f80beb3a61b74675169594b5f3f52..e945aea6dda6c9d242dad8bfeba263a01c675f16 100644 (file)
@@ -158,8 +158,17 @@ class ModulesInNamespace(IntegrationTestCase):
         self.run_doxygen(wildcard='*.xml')
         self.assertEqual(*self.actual_expected_contents('group__group1.html'))
         self.assertEqual(*self.actual_expected_contents('group__group2.html'))
-        self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html'))
-        self.assertEqual(*self.actual_expected_contents('file3_8h.html'))
+
+        # The change in https://github.com/doxygen/doxygen/issues/8790 is
+        # stupid because the XML is no longer self-contained. I refuse to
+        # implement parsing of nested XMLs, so the output will lack some
+        # members if groups are used.
+        if parse_version(doxygen_version()) > parse_version("1.9.7"):
+            self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html', 'namespaceNamespace-stupid.html'))
+            self.assertEqual(*self.actual_expected_contents('file3_8h.html', 'file3_8h-stupid.html'))
+        else:
+            self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html'))
+            self.assertEqual(*self.actual_expected_contents('file3_8h.html'))
 
 class Deprecated(IntegrationTestCase):
     def test(self):
@@ -248,7 +257,16 @@ class Includes(IntegrationTestCase):
         # group, even though in a single file, should have local includes; and
         # the SpreadClass struct is forward-declared in another file, which
         # triggers a silly Doxygen bug so it has per-member includes also
-        self.assertEqual(*self.actual_expected_contents('namespaceContained.html'))
+
+        # The change in https://github.com/doxygen/doxygen/issues/8790 is
+        # stupid because the XML is no longer self-contained. I refuse to
+        # implement parsing of nested XMLs, so the output will lack some
+        # members if groups are used.
+        if parse_version(doxygen_version()) > parse_version("1.9.7"):
+            self.assertEqual(*self.actual_expected_contents('namespaceContained.html', 'namespaceContained-stupid.html'))
+        else:
+            self.assertEqual(*self.actual_expected_contents('namespaceContained.html'))
+
         self.assertEqual(*self.actual_expected_contents('namespaceSpread.html'))
         self.assertEqual(*self.actual_expected_contents('classClass.html'))
         self.assertEqual(*self.actual_expected_contents('group__group.html'))
@@ -266,7 +284,15 @@ class IncludesDisabled(IntegrationTestCase):
 
         # No include information as SHOW_INCLUDE_FILES is disabled globally,
         # and no useless detailed sections either
-        self.assertEqual(*self.actual_expected_contents('namespaceContained.html'))
+
+        # The change in https://github.com/doxygen/doxygen/issues/8790 is
+        # stupid because the XML is no longer self-contained. I refuse to
+        # implement parsing of nested XMLs, so the output will lack some
+        # members if groups are used.
+        if parse_version(doxygen_version()) > parse_version("1.9.7"):
+            self.assertEqual(*self.actual_expected_contents('namespaceContained.html', 'namespaceContained-stupid.html'))
+        else:
+            self.assertEqual(*self.actual_expected_contents('namespaceContained.html'))
         self.assertEqual(*self.actual_expected_contents('namespaceSpread.html'))
         self.assertEqual(*self.actual_expected_contents('classClass.html'))
         self.assertEqual(*self.actual_expected_contents('group__group.html'))
@@ -279,7 +305,16 @@ class IncludesUndocumentedFiles(IntegrationTestCase):
         # The files are not documented, so there should be no include
         # information and no useless detailed sections either -- practically
         # the same output as when SHOW_INCLUDE_FILES is disabled globally
-        self.assertEqual(*self.actual_expected_contents('namespaceContained.html', '../compound_includes_disabled/namespaceContained.html'))
+
+        # The change in https://github.com/doxygen/doxygen/issues/8790 is
+        # stupid because the XML is no longer self-contained. I refuse to
+        # implement parsing of nested XMLs, so the output will lack some
+        # members if groups are used.
+        if parse_version(doxygen_version()) > parse_version("1.9.7"):
+            self.assertEqual(*self.actual_expected_contents('namespaceContained.html', '../compound_includes_disabled/namespaceContained-stupid.html'))
+        else:
+            self.assertEqual(*self.actual_expected_contents('namespaceContained.html', '../compound_includes_disabled/namespaceContained.html'))
+
         self.assertEqual(*self.actual_expected_contents('namespaceSpread.html', '../compound_includes_disabled/namespaceSpread.html'))
         self.assertEqual(*self.actual_expected_contents('classClass.html', '../compound_includes_disabled/classClass.html'))
         self.assertEqual(*self.actual_expected_contents('group__group.html', '../compound_includes_disabled/group__group.html'))
index 3bc42a937a3cbdabcfe4eed027cfcb1ec7243012..3c255154e614613417eff40f994bfba74008c55d 100644 (file)
@@ -443,7 +443,16 @@ class SectionsHeadings(IntegrationTestCase):
 class AnchorInBothGroupAndNamespace(IntegrationTestCase):
     def test(self):
         self.run_doxygen(wildcard='*.xml')
-        self.assertEqual(*self.actual_expected_contents('namespaceFoo.html'))
+
+        # The change in https://github.com/doxygen/doxygen/issues/8790 is
+        # stupid because the XML is no longer self-contained. I refuse to
+        # implement parsing of nested XMLs, so the output will lack some
+        # members if groups are used.
+        if parse_version(doxygen_version()) > parse_version("1.9.7"):
+            self.assertEqual(*self.actual_expected_contents('namespaceFoo.html', 'namespaceFoo-stupid.html'))
+        else:
+            self.assertEqual(*self.actual_expected_contents('namespaceFoo.html'))
+
         self.assertEqual(*self.actual_expected_contents('group__fizzbuzz.html'))
 
 class AnchorHtmlNoPrefixBug(IntegrationTestCase):
index a35a1be4c8382078a4c9a8d201d9247ee041882b..b4d83a42328b421a031ba2ae390479366d69965b 100644 (file)
@@ -29,7 +29,7 @@ import os
 
 from _search import Serializer, searchdata_filename
 
-from . import IntegrationTestCase
+from . import IntegrationTestCase, doxygen_version, parse_version
 
 class Undocumented(IntegrationTestCase):
     def test(self):
@@ -43,9 +43,18 @@ class Undocumented(IntegrationTestCase):
         self.assertEqual(*self.actual_expected_contents('classClass.html'))
 
         # Namespace, dir, file, group and class member listing
-        self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html'))
+
+        # The change in https://github.com/doxygen/doxygen/issues/8790 is
+        # stupid because the XML is no longer self-contained. I refuse to
+        # implement parsing of nested XMLs, so the output will lack some
+        # members if groups are used.
+        if parse_version(doxygen_version()) > parse_version("1.9.7"):
+            self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html', 'namespaceNamespace-stupid.html'))
+            self.assertEqual(*self.actual_expected_contents('File_8h.html', 'File_8h-stupid.html'))
+        else:
+            self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html'))
+            self.assertEqual(*self.actual_expected_contents('File_8h.html'))
         self.assertEqual(*self.actual_expected_contents('dir_4b0d5f8864bf89936129251a2d32609b.html'))
-        self.assertEqual(*self.actual_expected_contents('File_8h.html'))
         self.assertEqual(*self.actual_expected_contents('group__group.html'))
         self.assertEqual(*self.actual_expected_contents('structNamespace_1_1ClassInANamespace.html'))
 
@@ -55,4 +64,10 @@ class Undocumented(IntegrationTestCase):
         with open(os.path.join(self.path, 'html', searchdata_filename.format(search_filename_prefix='searchdata')), 'rb') as f:
             serialized = f.read()
             magic, version, type_data, symbol_count, map_offset, type_map_offset = Serializer.header_struct.unpack_from(serialized)
-            self.assertEqual(symbol_count, 44)
+
+            # See above, it's because certain symbols got skipped due to
+            # stupidity
+            if parse_version(doxygen_version()) > parse_version("1.9.7"):
+                self.assertEqual(symbol_count, 28)
+            else:
+                self.assertEqual(symbol_count, 44)
diff --git a/documentation/test_doxygen/undocumented/File_8h-stupid.html b/documentation/test_doxygen/undocumented/File_8h-stupid.html
new file mode 100644 (file)
index 0000000..4b7df5c
--- /dev/null
@@ -0,0 +1,183 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Directory/File.h file | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+      <div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
+        <a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
+          <path id="m-doc-search-icon-path" d="m6 0c-3.31 0-6 2.69-6 6 0 3.31 2.69 6 6 6 1.49 0 2.85-0.541 3.89-1.44-0.0164 0.338 0.147 0.759 0.5 1.15l3.22 3.79c0.552 0.614 1.45 0.665 2 0.115 0.55-0.55 0.499-1.45-0.115-2l-3.79-3.22c-0.392-0.353-0.812-0.515-1.15-0.5 0.895-1.05 1.44-2.41 1.44-3.89 0-3.31-2.69-6-6-6zm0 1.56a4.44 4.44 0 0 1 4.44 4.44 4.44 4.44 0 0 1-4.44 4.44 4.44 4.44 0 0 1-4.44-4.44 4.44 4.44 0 0 1 4.44-4.44z"/>
+        </svg></a>
+        <a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
+        <a id="m-navbar-hide" href="#" title="Hide navigation"></a>
+      </div>
+      <div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
+        <div class="m-row">
+          <ol class="m-col-t-6 m-col-m-none">
+            <li><a href="modules.html">Modules</a></li>
+            <li><a href="namespaces.html">Namespaces</a></li>
+          </ol>
+          <ol class="m-col-t-6 m-col-m-none" start="3">
+            <li><a href="annotated.html">Classes</a></li>
+            <li><a href="files.html">Files</a></li>
+            <li class="m-show-m"><a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
+              <use href="#m-doc-search-icon-path" />
+            </svg></a></li>
+          </ol>
+        </div>
+      </div>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          <span class="m-breadcrumb"><a href="dir_4b0d5f8864bf89936129251a2d32609b.html">Directory</a>/</span>File.h <span class="m-thin">file</span>
+        </h1>
+        <p><span></span></p>
+        <nav class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#namespaces">Namespaces</a></li>
+                <li><a href="#nested-classes">Classes</a></li>
+                <li><a href="#define-members">Defines</a></li>
+                <li><a href="#a-group">A group</a></li>
+              </ul>
+            </li>
+          </ul>
+        </nav>
+        <section id="namespaces">
+          <h2><a href="#namespaces">Namespaces</a></h2>
+          <dl class="m-doc">
+            <dt>namespace <a href="namespaceNamespace.html" class="m-doc">Namespace</a></dt>
+            <dd><span></span></dd>
+          </dl>
+        </section>
+        <section id="nested-classes">
+          <h2><a href="#nested-classes">Classes</a></h2>
+          <dl class="m-doc">
+            <dt>
+              class <a href="classClass.html" class="m-doc">Class</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              struct <a href="structStruct.html" class="m-doc">Struct</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              union <a href="unionUnion.html" class="m-doc">Union</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              struct <a href="structNamespace_1_1ClassInANamespace.html" class="m-doc">Namespace::ClassInANamespace</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              class <a href="classNamespace_1_1ClassInANamespace_1_1ClassInAClass.html" class="m-doc">Namespace::ClassInANamespace::ClassInAClass</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              class <a href="classNamespace_1_1ClassInModule.html" class="m-doc">Namespace::ClassInModule</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              struct <a href="structNamespace_1_1StructInModule.html" class="m-doc">Namespace::StructInModule</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              union <a href="unionNamespace_1_1UnionInModule.html" class="m-doc">Namespace::UnionInModule</a>
+            </dt>
+            <dd><span></span></dd>
+          </dl>
+        </section>
+        <section id="define-members">
+          <h2><a href="#define-members">Defines</a></h2>
+          <dl class="m-doc">
+            <dt id="a144a2a84c08d05de76f6a4a245584810">
+              <span class="m-doc-wrap-bumper">#define <a href="#a144a2a84c08d05de76f6a4a245584810" class="m-doc-self">A_DEFINE</a></span>
+            </dt>
+            <dd><span></span></dd>
+          </dl>
+        </section>
+        <section id="a-group">
+          <h2><a href="#a-group">A group</a></h2>
+          <dl class="m-doc">
+            <dt id="ac8ab78e5a895bc0dfceb61c9b7707dbe">
+              <span class="m-doc-wrap-bumper">#define <a href="#ac8ab78e5a895bc0dfceb61c9b7707dbe" class="m-doc-self">A_DEFINE_IN_A_GROUP</a></span>
+            </dt>
+            <dd><span></span></dd>
+            <dt id="a4e54d99b64c66ac62367c340296cf0e6">
+              <span class="m-doc-wrap-bumper">enum <a href="#a4e54d99b64c66ac62367c340296cf0e6" class="m-doc-self">FlagInAGroup</a> { </span><span class="m-doc-wrap"> }</span>
+            </dt>
+            <dd><span></span></dd>
+            <dt id="a71f74df9fc21890c995ff83a0d3fac55">
+              using <a href="#a71f74df9fc21890c995ff83a0d3fac55" class="m-doc-self">MainInAGroup</a> = void
+            </dt>
+            <dd><span></span></dd>
+            <dt id="addafc81fb6e46828eada927103080acc">
+              void* <a href="#addafc81fb6e46828eada927103080acc" class="m-doc-self">variableInAGroup</a> <span class="m-label m-flat m-primary">constexpr</span>
+            </dt>
+            <dd><span></span></dd>
+            <dt id="a34b4421352d415dad9bf0c6a2e4694d4">
+              <span class="m-doc-wrap-bumper">void <a href="#a34b4421352d415dad9bf0c6a2e4694d4" class="m-doc-self">barInAGroup</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd><span></span></dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+<div class="m-doc-search" id="search">
+  <a href="#!" onclick="return hideSearch()"></a>
+  <div class="m-container">
+    <div class="m-row">
+      <div class="m-col-m-8 m-push-m-2">
+        <div class="m-doc-search-header m-text m-small">
+          <div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
+          <div id="search-symbolcount">&hellip;</div>
+        </div>
+        <div class="m-doc-search-content">
+          <form>
+            <input type="search" name="q" id="search-input" placeholder="Loading &hellip;" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
+          </form>
+          <noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
+          <div id="search-help" class="m-text m-dim m-text-center">
+            <p class="m-noindent">Search for symbols, directories, files, pages or
+            modules. You can omit any prefix from the symbol or file path; adding a
+            <code>:</code> or <code>/</code> suffix lists all members of given symbol or
+            directory.</p>
+            <p class="m-noindent">Use <span class="m-label m-dim">&darr;</span>
+            / <span class="m-label m-dim">&uarr;</span> to navigate through the list,
+            <span class="m-label m-dim">Enter</span> to go.
+            <span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
+            copy a link to the result using <span class="m-label m-dim">⌘</span>
+            <span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
+            <span class="m-label m-dim">M</span> produces a Markdown link.</p>
+          </div>
+          <div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
+          <ul id="search-results"></ul>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+<script src="search-v2.js"></script>
+<script>
+  Search.download(window.location.pathname.substr(0, window.location.pathname.lastIndexOf('/') + 1) + 'searchdata-v2.bin');
+</script>
+</body>
+</html>
diff --git a/documentation/test_doxygen/undocumented/namespaceNamespace-stupid.html b/documentation/test_doxygen/undocumented/namespaceNamespace-stupid.html
new file mode 100644 (file)
index 0000000..c9dea03
--- /dev/null
@@ -0,0 +1,145 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Namespace namespace | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+      <div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
+        <a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
+          <path id="m-doc-search-icon-path" d="m6 0c-3.31 0-6 2.69-6 6 0 3.31 2.69 6 6 6 1.49 0 2.85-0.541 3.89-1.44-0.0164 0.338 0.147 0.759 0.5 1.15l3.22 3.79c0.552 0.614 1.45 0.665 2 0.115 0.55-0.55 0.499-1.45-0.115-2l-3.79-3.22c-0.392-0.353-0.812-0.515-1.15-0.5 0.895-1.05 1.44-2.41 1.44-3.89 0-3.31-2.69-6-6-6zm0 1.56a4.44 4.44 0 0 1 4.44 4.44 4.44 4.44 0 0 1-4.44 4.44 4.44 4.44 0 0 1-4.44-4.44 4.44 4.44 0 0 1 4.44-4.44z"/>
+        </svg></a>
+        <a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
+        <a id="m-navbar-hide" href="#" title="Hide navigation"></a>
+      </div>
+      <div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
+        <div class="m-row">
+          <ol class="m-col-t-6 m-col-m-none">
+            <li><a href="modules.html">Modules</a></li>
+            <li><a href="namespaces.html">Namespaces</a></li>
+          </ol>
+          <ol class="m-col-t-6 m-col-m-none" start="3">
+            <li><a href="annotated.html">Classes</a></li>
+            <li><a href="files.html">Files</a></li>
+            <li class="m-show-m"><a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
+              <use href="#m-doc-search-icon-path" />
+            </svg></a></li>
+          </ol>
+        </div>
+      </div>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          Namespace <span class="m-thin">namespace</span>
+        </h1>
+        <p><span></span></p>
+        <nav class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#nested-classes">Classes</a></li>
+                <li><a href="#a-group">A group</a></li>
+              </ul>
+            </li>
+          </ul>
+        </nav>
+        <section id="nested-classes">
+          <h2><a href="#nested-classes">Classes</a></h2>
+          <dl class="m-doc">
+            <dt>
+              struct <a href="structNamespace_1_1ClassInANamespace.html" class="m-doc">ClassInANamespace</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              class <a href="classNamespace_1_1ClassInModule.html" class="m-doc">ClassInModule</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              struct <a href="structNamespace_1_1StructInModule.html" class="m-doc">StructInModule</a>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              union <a href="unionNamespace_1_1UnionInModule.html" class="m-doc">UnionInModule</a>
+            </dt>
+            <dd><span></span></dd>
+          </dl>
+        </section>
+        <section id="a-group">
+          <h2><a href="#a-group">A group</a></h2>
+          <dl class="m-doc">
+            <dt>
+              <span class="m-doc-wrap-bumper">enum <a href="File_8h.html#a4e54d99b64c66ac62367c340296cf0e6" class="m-doc">FlagInAGroup</a> { </span><span class="m-doc-wrap"> }</span>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              using <a href="File_8h.html#a71f74df9fc21890c995ff83a0d3fac55" class="m-doc">MainInAGroup</a> = void
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              void* <a href="File_8h.html#addafc81fb6e46828eada927103080acc" class="m-doc">variableInAGroup</a> <span class="m-label m-flat m-primary">constexpr</span>
+            </dt>
+            <dd><span></span></dd>
+            <dt>
+              <span class="m-doc-wrap-bumper">void <a href="File_8h.html#a34b4421352d415dad9bf0c6a2e4694d4" class="m-doc">barInAGroup</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd><span></span></dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+<div class="m-doc-search" id="search">
+  <a href="#!" onclick="return hideSearch()"></a>
+  <div class="m-container">
+    <div class="m-row">
+      <div class="m-col-m-8 m-push-m-2">
+        <div class="m-doc-search-header m-text m-small">
+          <div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
+          <div id="search-symbolcount">&hellip;</div>
+        </div>
+        <div class="m-doc-search-content">
+          <form>
+            <input type="search" name="q" id="search-input" placeholder="Loading &hellip;" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
+          </form>
+          <noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
+          <div id="search-help" class="m-text m-dim m-text-center">
+            <p class="m-noindent">Search for symbols, directories, files, pages or
+            modules. You can omit any prefix from the symbol or file path; adding a
+            <code>:</code> or <code>/</code> suffix lists all members of given symbol or
+            directory.</p>
+            <p class="m-noindent">Use <span class="m-label m-dim">&darr;</span>
+            / <span class="m-label m-dim">&uarr;</span> to navigate through the list,
+            <span class="m-label m-dim">Enter</span> to go.
+            <span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
+            copy a link to the result using <span class="m-label m-dim">⌘</span>
+            <span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
+            <span class="m-label m-dim">M</span> produces a Markdown link.</p>
+          </div>
+          <div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
+          <ul id="search-results"></ul>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+<script src="search-v2.js"></script>
+<script>
+  Search.download(window.location.pathname.substr(0, window.location.pathname.lastIndexOf('/') + 1) + 'searchdata-v2.bin');
+</script>
+</body>
+</html>