From 62768962f9cf167291bae2df518de0c89d6836cf Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Sun, 15 Sep 2024 14:31:22 +0200
Subject: [PATCH] documentation/doxygen: ignore unsupported languages instead
 of blowing up.

Should have done this from the beginning instead of repeatedly telling
people that the cannot include JS or python files as part of the doc
build.

Interestingly enough, file.js gets still treated as C++. Had to switch to
Java to make it detect as something that's not C++.
---
 doc/documentation/doxygen.rst                 |  9 +++-
 documentation/doxygen.py                      |  9 ++++
 .../test_doxygen/ignored_languages/Doxyfile   | 15 ++++++
 .../test_doxygen/ignored_languages/file.c     |  6 +++
 .../test_doxygen/ignored_languages/file.cs    |  3 ++
 .../test_doxygen/ignored_languages/file.java  |  3 ++
 .../test_doxygen/ignored_languages/file.py    |  3 ++
 .../ignored_languages/file_8c.html            | 52 +++++++++++++++++++
 .../{test_ignored_xmls.py => test_ignored.py} | 25 ++++++++-
 9 files changed, 122 insertions(+), 3 deletions(-)
 create mode 100644 documentation/test_doxygen/ignored_languages/Doxyfile
 create mode 100644 documentation/test_doxygen/ignored_languages/file.c
 create mode 100644 documentation/test_doxygen/ignored_languages/file.cs
 create mode 100644 documentation/test_doxygen/ignored_languages/file.java
 create mode 100644 documentation/test_doxygen/ignored_languages/file.py
 create mode 100644 documentation/test_doxygen/ignored_languages/file_8c.html
 rename documentation/test_doxygen/{test_ignored_xmls.py => test_ignored.py} (66%)

diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst
index 5bd54afc..a1fe79a7 100644
--- a/doc/documentation/doxygen.rst
+++ b/doc/documentation/doxygen.rst
@@ -205,8 +205,15 @@ In addition to features `shared by all doc generators <{filename}/documentation.
 
     This list presents my opinions. Not everybody likes my opinions.
 
+The theme is deliberately *only* for C and C++. See the `Python documentation generator <{filename}/python.rst>`__
+for a dedicated tool handling Python. Other languages such as C# or Java would
+be also better handled using dedicated tools that can make use of reflection
+features built into the language itself instead of attempting to (badly) parse
+the sources, plus a dedicated tool can better adjust to specifics of given
+language, such as not calling Python or Java packages "namespaces".
+
 Features that I don't see a point in because they just artificially inflate the
-amount of generated content for no added value.
+amount of generated content for no added value:
 
 -   Class hierarchy graphs are ignored (it only inflates the documentation with
     little added value)
diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 27d4d869..4ce662d0 100755
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -2403,6 +2403,12 @@ def extract_metadata(state: State, xml):
     if compounddef.tag != 'compounddef':
         logging.warning("{}: first child element expected to be <compounddef> but is <{}>, skipping whole file".format(state.current, compounddef.tag))
         return
+    # Using `in []` to prepare for potential future additions like 'C', but so
+    # far Doxygen treats even *.c files as language="C++". Reproduced in the
+    # test_ignored.Languages test case.
+    if compounddef.attrib.get('language', 'C++') not in ['C++']:
+        logging.warning("{}: unsupported language {}, skipping whole file".format(state.current, compounddef.attrib['language']))
+        return
     assert len([i for i in root]) == 1
 
     if compounddef.attrib['kind'] not in ['namespace', 'group', 'class', 'struct', 'union', 'dir', 'file', 'page']:
@@ -2711,6 +2717,9 @@ def parse_xml(state: State, xml: str):
     compounddef: ET.Element = root[0]
     if compounddef.tag != 'compounddef':
         return
+    # See extract_metadata() for why `in []` is used
+    if compounddef.attrib.get('language', 'C++') not in ['C++']:
+        return
 
     assert len([i for i in root]) == 1
 
diff --git a/documentation/test_doxygen/ignored_languages/Doxyfile b/documentation/test_doxygen/ignored_languages/Doxyfile
new file mode 100644
index 00000000..5d5a7d37
--- /dev/null
+++ b/documentation/test_doxygen/ignored_languages/Doxyfile
@@ -0,0 +1,15 @@
+INPUT                   = file.c file.cs file.java file.py
+AUTOLINK_SUPPORT        = NO
+QUIET                   = YES
+GENERATE_HTML           = NO
+GENERATE_LATEX          = NO
+GENERATE_XML            = YES
+XML_PROGRAMLISTING      = NO
+CASE_SENSE_NAMES        = YES
+
+##! M_PAGE_FINE_PRINT   =
+##! M_THEME_COLOR       =
+##! M_FAVICON           =
+##! M_LINKS_NAVBAR1     =
+##! M_LINKS_NAVBAR2     =
+##! M_SEARCH_DISABLED   = YES
diff --git a/documentation/test_doxygen/ignored_languages/file.c b/documentation/test_doxygen/ignored_languages/file.c
new file mode 100644
index 00000000..c22bc1df
--- /dev/null
+++ b/documentation/test_doxygen/ignored_languages/file.c
@@ -0,0 +1,6 @@
+/** @file
+ * @brief A C file, which should stay
+ */
+
+/** @brief A typesafe C function */
+void foo(void** const**, ...);
diff --git a/documentation/test_doxygen/ignored_languages/file.cs b/documentation/test_doxygen/ignored_languages/file.cs
new file mode 100644
index 00000000..72766808
--- /dev/null
+++ b/documentation/test_doxygen/ignored_languages/file.cs
@@ -0,0 +1,3 @@
+/** @file
+ * @brief A C# file, should be ignored
+ */
diff --git a/documentation/test_doxygen/ignored_languages/file.java b/documentation/test_doxygen/ignored_languages/file.java
new file mode 100644
index 00000000..654be44a
--- /dev/null
+++ b/documentation/test_doxygen/ignored_languages/file.java
@@ -0,0 +1,3 @@
+/** @file
+ * @brief A JS file, should be ignored
+ */
diff --git a/documentation/test_doxygen/ignored_languages/file.py b/documentation/test_doxygen/ignored_languages/file.py
new file mode 100644
index 00000000..2feed947
--- /dev/null
+++ b/documentation/test_doxygen/ignored_languages/file.py
@@ -0,0 +1,3 @@
+""" @package file
+@brief A Python file, should be ignored
+"""
diff --git a/documentation/test_doxygen/ignored_languages/file_8c.html b/documentation/test_doxygen/ignored_languages/file_8c.html
new file mode 100644
index 00000000..fa99fe2d
--- /dev/null
+++ b/documentation/test_doxygen/ignored_languages/file_8c.html
@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>file.c 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>
+          file.c <span class="m-thin">file</span>
+        </h1>
+        <p>A C file, which should stay.</p>
+        <nav class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#func-members">Functions</a></li>
+              </ul>
+            </li>
+          </ul>
+        </nav>
+        <section id="func-members">
+          <h2><a href="#func-members">Functions</a></h2>
+          <dl class="m-doc">
+            <dt id="a5e34add4910fa88bec86efb850d018c3">
+              <span class="m-doc-wrap-bumper">void <a href="#a5e34add4910fa88bec86efb850d018c3" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">void**const**,
+              ...)</span>
+            </dt>
+            <dd>A typesafe C function.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>
diff --git a/documentation/test_doxygen/test_ignored_xmls.py b/documentation/test_doxygen/test_ignored.py
similarity index 66%
rename from documentation/test_doxygen/test_ignored_xmls.py
rename to documentation/test_doxygen/test_ignored.py
index f7cbd31c..5932087f 100644
--- a/documentation/test_doxygen/test_ignored_xmls.py
+++ b/documentation/test_doxygen/test_ignored.py
@@ -25,9 +25,9 @@
 
 import os
 
-from . import BaseTestCase
+from . import BaseTestCase, IntegrationTestCase, doxygen_version, parse_version
 
-class IgnoredXmls(BaseTestCase):
+class Xmls(BaseTestCase):
     def test(self):
         with self.assertLogs() as cm:
             self.run_doxygen(wildcard='*.xml')
@@ -54,3 +54,24 @@ class IgnoredXmls(BaseTestCase):
         # Some index page should be generated, with version 1.0.666 extracted
         # from index.xml
         self.assertEqual(*self.actual_expected_contents('pages.html'))
+
+class Languages(IntegrationTestCase):
+    def test(self):
+        with self.assertLogs() as cm:
+            self.run_doxygen(index_pages=[], wildcard='*.xml')
+
+        expected = [
+            'WARNING:root:file_8cs.xml: unsupported language C#, skipping whole file',
+            'WARNING:root:file_8java.xml: unsupported language Java, skipping whole file',
+            'WARNING:root:file_8py.xml: unsupported language Python, skipping whole file',
+            'WARNING:root:namespacefile.xml: unsupported language Python, skipping whole file'
+        ]
+        # Doxygen 1.9.3 (?) generates one more strange file for Java
+        if parse_version(doxygen_version()) >= parse_version("1.9.3"):
+            expected += ['WARNING:root:namespacejava_1_1lang.xml: unsupported language Java, skipping whole file']
+        self.assertEqual(cm.output, expected)
+
+        # C files shouldn't be ignored. Testing explicitly as the rest of the
+        # tests is all C++ files. Right now, Doxygen says the language is C++
+        # as well, but that might change in the future, so have that verified.
+        self.assertEqual(*self.actual_expected_contents('file_8c.html'))
-- 
2.30.2