documentation/doxygen: don't use <includes> w/o STRIP_FROM_PATH defined.

The damn thing then just strips all directories and keeps just the leaf
name, which is completely useless. One would think setting
STRIP_FROM_INC_PATH to `.` is the same as leaving it empty, but
apparently not!

diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst
index b222101ea50648978fb69da90c1571f9c6d31167..b21068fa25bd05cf89e82896d6f64ebc22a8c50d 100644 (file)
--- a/doc/documentation/doxygen.rst
+++ b/doc/documentation/doxygen.rst
@@ -303,6 +303,18 @@ Variable                        Description
                                 glaringly useless in every imaginable way and
                                 thus the theme is reusing it for something
                                 actually useful. Doxygen default is ``YES``.
+:ini:`STRIP_FROM_PATH`          Prefix to strip from directory and file paths
+                                shown in page titles.
+:ini:`STRIP_FROM_INC_PATH`      Prefix to strip from paths of :cpp:`#include`
+                                files shown for classes, namespaces and
+                                namespace members. Often set to the same value
+                                as :ini:`STRIP_FROM_INC_PATH`. Note that you
+                                have to set this option to something non-empty
+                                if you're using header name overrides in the
+                                `@class <https://www.doxygen.nl/manual/commands.html#cmdclass>`_
+                                command --- otherwise Doxygen strips all
+                                directory information from include files which
+                                m.css then has no way of restoring.
 =============================== ===============================================
 
 On top of the above, the script can take additional options in a way consistent

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 638ce1b16b397a9f1c90547a3002b8fdbd2e5238..8862b83fac7a5f6e0d4e5f5bd38494460d542b91 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -2890,8 +2890,13 @@ def parse_xml(state: State, xml: str):
         # provided ID as the include link target and the name as the include
         # name. Otherwise the information is extracted from the <location> tag.
         # See test_compound.IncludesStripFromPath for a test case.
+        #
+        # Apparently, if STRIP_FROM_INC_PATH isn't set at all in the Doxyfile,
+        # the damn thing does the worst possible and keeps just the leaf
+        # filename there. Which is useless, so assume that if someone wants
+        # to override include names, they also set STRIP_FROM_INC_PATH.
         compound_includes = compounddef.find('includes')
-        if compound.kind in ['struct', 'class', 'union'] and compound_includes is not None:
+        if state.doxyfile['STRIP_FROM_INC_PATH'] and compound.kind in ['struct', 'class', 'union'] and compound_includes is not None:
             compound.include = make_class_include(state, compound_includes.attrib['refid'], compound_includes.text)
         else:
             compound.include = make_include(state, file)

diff --git a/documentation/test_doxygen/__init__.py b/documentation/test_doxygen/__init__.py
index 7607d7f1ff212f5165b362f3580b8d5a9c43968a..c83291a7dad4c91ee91a2d744146e206d698852c 100644 (file)
--- a/documentation/test_doxygen/__init__.py
+++ b/documentation/test_doxygen/__init__.py
@@ -52,9 +52,11 @@ def parse_version(string: str):
     return tuple([int(i) for i in string.split('.')])
 
 class BaseTestCase(unittest.TestCase):
-    def __init__(self, *args, dir=None, **kwargs):
+    def __init__(self, *args, dir=None, doxyfile='Doxyfile', **kwargs):
         unittest.TestCase.__init__(self, *args, **kwargs)
 
+        self.doxyfile = doxyfile
+
         # Get the test filename from the derived class module file. If path is
         # not supplied, get it from derived class name converted to snake_case
         path = sys.modules[self.__class__.__module__].__file__
@@ -81,7 +83,7 @@ class BaseTestCase(unittest.TestCase):
 
     def run_doxygen(self, templates=default_templates, wildcard=default_wildcard, index_pages=default_index_pages, config={}):
         state = State({**copy.deepcopy(default_config), **config})
-        parse_doxyfile(state, os.path.join(self.path, 'Doxyfile'))
+        parse_doxyfile(state, os.path.join(self.path, self.doxyfile))
         run(state, templates=templates, wildcard=wildcard, index_pages=index_pages, sort_globbed_files=True)
 
     def actual_expected_contents(self, actual, expected = None):
@@ -97,6 +99,6 @@ class BaseTestCase(unittest.TestCase):
 class IntegrationTestCase(BaseTestCase):
     def setUp(self):
         if os.path.exists(os.path.join(self.path, 'xml')): shutil.rmtree(os.path.join(self.path, 'xml'))
-        subprocess.run(['doxygen'], cwd=self.path, check=True)
+        subprocess.run(['doxygen', self.doxyfile], cwd=self.path, check=True)
 
         if os.path.exists(os.path.join(self.path, 'html')): shutil.rmtree(os.path.join(self.path, 'html'))

diff --git a/documentation/test_doxygen/compound_listing/Doxyfile b/documentation/test_doxygen/compound_listing/Doxyfile
index cf34078a49971de3bbae69c16c5544724ab50fdc..07e48f7ad911b5a986b830fa5a2727156155e4b4 100644 (file)
--- a/documentation/test_doxygen/compound_listing/Doxyfile
+++ b/documentation/test_doxygen/compound_listing/Doxyfile
@@ -9,6 +9,12 @@ GENERATE_XML            = YES
 XML_PROGRAMLISTING      = NO
 CASE_SENSE_NAMES        = YES
 
+# This deliberately doesn't have STRIP_FROM_PATH / STRIP_FROM_INC_PATH to
+# verify correct behavior with subdirs being preserved by default. The
+# Doxyfile-strip-from-path and the ListingStripFromPath test then sets
+# STRIP_FROM_INC_PATH to a trivial value, which then should give the exact same
+# result.
+
 ##! M_FILE_TREE_EXPAND_LEVELS = 2
 ##! M_CLASS_TREE_EXPAND_LEVELS = 5
 ##! M_EXPAND_INNER_TYPES = YES

diff --git a/documentation/test_doxygen/compound_listing/Doxyfile-strip-from-path b/documentation/test_doxygen/compound_listing/Doxyfile-strip-from-path
new file mode 100644 (file)
index 0000000..25a75dc
--- /dev/null
+++ b/documentation/test_doxygen/compound_listing/Doxyfile-strip-from-path
@@ -0,0 +1,7 @@
+@INCLUDE                = Doxyfile
+
+# Without this, Doxygen strips all directories from <includes> elements, losing
+# the actual filesystem hierarchy. M.css detects that and uses <location>
+# instead. This then verifies that the output is the same with
+# STRIP_FROM_INC_PATH not set at all and set to a trivial value.
+STRIP_FROM_INC_PATH     = .

diff --git a/documentation/test_doxygen/test_compound.py b/documentation/test_doxygen/test_compound.py
index a53418e26cc7a35fb3e802a5129f2304d9bde161..6a137e8506d500809776b00f4d09f12c206f59d8 100644 (file)
--- a/documentation/test_doxygen/test_compound.py
+++ b/documentation/test_doxygen/test_compound.py
@@ -31,6 +31,9 @@ import unittest
 from . import IntegrationTestCase, doxygen_version, parse_version
 
 class Listing(IntegrationTestCase):
+    def __init__(self, *args, **kwargs):
+        IntegrationTestCase.__init__(self, *args, **kwargs)
+
     def test_index_pages(self):
         self.run_doxygen(wildcard='index.xml', index_pages=['annotated', 'namespaces', 'pages'])
         self.assertEqual(*self.actual_expected_contents('annotated.html'))
@@ -76,6 +79,13 @@ class Listing(IntegrationTestCase):
         self.run_doxygen(wildcard='page-no-toc.xml')
         self.assertEqual(*self.actual_expected_contents('page-no-toc.html'))
 
+# Like Listing, but tests with STRIP_FROM_INC_PATH set to a trivial value.
+# Both should result in the exact same output regardless of any Doxygen warts
+# inside.
+class ListingStripFromPath(Listing):
+    def __init__(self, *args, **kwargs):
+        Listing.__init__(self, *args, dir='listing', doxyfile='Doxyfile-strip-from-path', **kwargs)
+
 class Detailed(IntegrationTestCase):
     def test_namespace(self):
         self.run_doxygen(wildcard='namespaceNamee.xml')