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++.

diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst
index 5bd54afcf2d59d68c4f79b98c60e1ff47c81217d..a1fe79a75626cf30c0d3ddbe2fe2360145e39835 100644 (file)
--- 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 27d4d8696aa26367a106014b20009b48acf61a96..4ce662d053024c506539b6bc96568b5e767f29a4 100755 (executable)
--- 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 (file)
index 0000000..5d5a7d3
--- /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 (file)
index 0000000..c22bc1d
--- /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 (file)
index 0000000..7276680
--- /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 (file)
index 0000000..654be44
--- /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 (file)
index 0000000..2feed94
--- /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 (file)
index 0000000..fa99fe2
--- /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 f7cbd31cb72f4ca69c7e77df30989615988959e1..5932087f461dd4f08ec8f7d8412a0da93ea69a49 100644 (file)
--- 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'))