From 319479ef48e4eadd06b5d8b2eb353cac32c29455 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 15 Sep 2024 21:19:50 +0200 Subject: [PATCH] documentation/doxygen: don't use 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! --- doc/documentation/doxygen.rst | 12 ++++++++++++ documentation/doxygen.py | 7 ++++++- documentation/test_doxygen/__init__.py | 8 +++++--- documentation/test_doxygen/compound_listing/Doxyfile | 6 ++++++ .../compound_listing/Doxyfile-strip-from-path | 7 +++++++ documentation/test_doxygen/test_compound.py | 10 ++++++++++ 6 files changed, 46 insertions(+), 4 deletions(-) create mode 100644 documentation/test_doxygen/compound_listing/Doxyfile-strip-from-path diff --git a/doc/documentation/doxygen.rst b/doc/documentation/doxygen.rst index b222101e..b21068fa 100644 --- 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 `_ + 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 638ce1b1..8862b83f 100755 --- 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 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 7607d7f1..c83291a7 100644 --- 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 cf34078a..07e48f7a 100644 --- 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 index 00000000..25a75dca --- /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 elements, losing +# the actual filesystem hierarchy. M.css detects that and uses +# 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 a53418e2..6a137e85 100644 --- 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') -- 2.30.2