From 083c7a87dcca80027a4bc9c5e6db3bab4babffb0 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 16 Sep 2024 19:59:42 +0200 Subject: [PATCH] documentation/doxygen: this warning isn't related to any file. It may get printed when preprocessing the state from all files (building parent/child hierarchies, etc), listing a random file for that is extremely confusing. Well, the whole message is extremely confusing, so let's redo it, suggest a fix and also have a test for it, instead of excluding it from coverage. --- documentation/doxygen.py | 4 +- documentation/test_doxygen/__init__.py | 5 +- .../compound_no_full_path_names/doc/Doxyfile | 21 +++++++ .../compound_no_full_path_names/files.html | 58 +++++++++++++++++++ .../project/directory/sub.h | 3 + .../project/root.h | 14 +++++ documentation/test_doxygen/test_compound.py | 13 +++++ 7 files changed, 115 insertions(+), 3 deletions(-) create mode 100644 documentation/test_doxygen/compound_no_full_path_names/doc/Doxyfile create mode 100644 documentation/test_doxygen/compound_no_full_path_names/files.html create mode 100644 documentation/test_doxygen/compound_no_full_path_names/project/directory/sub.h create mode 100644 documentation/test_doxygen/compound_no_full_path_names/project/root.h diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 530d6db2..8502d5e9 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -2602,8 +2602,8 @@ def postprocess_state(state: State): prefix = state.compounds[compound.parent].name + '/' if compound.name.startswith(prefix): compound.leaf_name = compound.name[len(prefix):] - else: # pragma: no cover - logging.warning("{}: potential issue: directory {} parent is not a prefix: {}".format(state.current, compound.name, prefix)) + else: + logging.warning("potential issue: the parent of {}/ is {} which is not a prefix, you may want to enable FULL_PATH_NAMES together with STRIP_FROM_PATH and STRIP_FROM_INC_PATH to preserve filesystem hierarchy".format(compound.name, prefix)) compound.leaf_name = compound.name # Other compounds are not in any index pages or breadcrumb, so leaf diff --git a/documentation/test_doxygen/__init__.py b/documentation/test_doxygen/__init__.py index c83291a7..a238d9b5 100644 --- a/documentation/test_doxygen/__init__.py +++ b/documentation/test_doxygen/__init__.py @@ -99,6 +99,9 @@ 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', self.doxyfile], cwd=self.path, check=True) + # Run Doxygen at the path where Doxyfile is, in order to interpret the + # paths in it relative to that file + subpath, doxyfile = os.path.split(self.doxyfile) + subprocess.run(['doxygen', doxyfile], cwd=os.path.join(self.path, subpath), 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_no_full_path_names/doc/Doxyfile b/documentation/test_doxygen/compound_no_full_path_names/doc/Doxyfile new file mode 100644 index 00000000..68aadcf4 --- /dev/null +++ b/documentation/test_doxygen/compound_no_full_path_names/doc/Doxyfile @@ -0,0 +1,21 @@ +INPUT = ../project/root.h ../project/directory/sub.h +OUTPUT_DIRECTORY = .. +QUIET = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_PROGRAMLISTING = NO +CASE_SENSE_NAMES = YES + +# If the three below would be set instead, it wouldn't warn +FULL_PATH_NAMES = NO +# FULL_PATH_NAMES = YES +# STRIP_FROM_PATH = .. +# STRIP_FROM_INC_PATH = .. + +##! 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/compound_no_full_path_names/files.html b/documentation/test_doxygen/compound_no_full_path_names/files.html new file mode 100644 index 00000000..4e07d8c6 --- /dev/null +++ b/documentation/test_doxygen/compound_no_full_path_names/files.html @@ -0,0 +1,58 @@ + + + + + My Project + + + + + +
+
+
+
+
+

Files

+ + +
+
+
+
+ + diff --git a/documentation/test_doxygen/compound_no_full_path_names/project/directory/sub.h b/documentation/test_doxygen/compound_no_full_path_names/project/directory/sub.h new file mode 100644 index 00000000..2d98ffa1 --- /dev/null +++ b/documentation/test_doxygen/compound_no_full_path_names/project/directory/sub.h @@ -0,0 +1,3 @@ +/** @file + * @brief Subdirectory file + */ diff --git a/documentation/test_doxygen/compound_no_full_path_names/project/root.h b/documentation/test_doxygen/compound_no_full_path_names/project/root.h new file mode 100644 index 00000000..793c3e70 --- /dev/null +++ b/documentation/test_doxygen/compound_no_full_path_names/project/root.h @@ -0,0 +1,14 @@ +/* Sources for the test in ../compound_no_full_path_names, needs to be in a + directory outside of the Doxyfile to trigger the behavior */ + +/** @dir project + * @brief Root directory + */ + +/** @dir project/directory + * @brief Subdirectory + */ + +/** @file + * @brief Root file + */ diff --git a/documentation/test_doxygen/test_compound.py b/documentation/test_doxygen/test_compound.py index 6a137e85..1e239ea6 100644 --- a/documentation/test_doxygen/test_compound.py +++ b/documentation/test_doxygen/test_compound.py @@ -428,3 +428,16 @@ class InlineNamespace(IntegrationTestCase): self.assertEqual(*self.actual_expected_contents('File_8h.html')) self.assertEqual(*self.actual_expected_contents('annotated.html')) self.assertEqual(*self.actual_expected_contents('namespaces.html')) + +class NoFullPathNames(IntegrationTestCase): + def __init__(self, *args, **kwargs): + Listing.__init__(self, *args, doxyfile='doc/Doxyfile', **kwargs) + + def test(self): + with self.assertLogs() as cm: + self.run_doxygen(wildcard='*.xml') + + self.assertEqual(*self.actual_expected_contents('files.html')) + self.assertEqual(cm.output, [ + "WARNING:root:potential issue: the parent of directory/ is project/ which is not a prefix, you may want to enable FULL_PATH_NAMES together with STRIP_FROM_PATH and STRIP_FROM_INC_PATH to preserve filesystem hierarchy" + ]) -- 2.30.2