documentation/doxygen: support for STRIP_FROM{,_INC}_PATH.

Doxygen support for STRIP_FROM_INC_PATH is applied to class/struct and
enums through the <includes> xml tag. m.css additionaly shows such
information for functions, enum, namespaces, typedef, variables and
defines through the information extracted from the <location file="xx"/>
tag.

However the location available through the <location file="xx"/> is not
stripped using STRIP_FROM_INC_PATH, only STRIP_FROM_PATH.

This patch provides STRIP_FROM_INC_PATH support by building the prefixes
(STRIP_FROM_INC_PATH stripped from STRIP_FROM_PATH) and stripping the
longest match when constructing the include html.

Co-authored-by: Yuri Edward <nicolas1.fraysse@epitech.eu>
Co-authored-by: Vladimír Vondruš <mosra@centrum.cz>

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 5a17deb1b25930920bc25a9f3d523f8a740ca825..f3d2e94d78ae720176033caeb17fa1386ea42da6 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -260,9 +260,20 @@ def parse_ref(state: State, element: ET.Element, add_inline_css_class: str = Non
 
     return '<a href="{}" class="{}">{}</a>'.format(url, class_, add_wbr(parse_inline_desc(state, element).strip()))
 
+# Returns a shortened path if the prefix matches
+def remove_path_prefix(path: str, prefix: str) -> str:
+    common_path = os.path.commonprefix([path, prefix])
+    return path[len(common_path):].lstrip(os.path.sep) if common_path else path
+
+# Return the string that has the longest prefix stripped, as defined by Doxygen
+# in src/util.cpp
+def make_include_strip_from_path(path: str, prefixes: List[str]) -> str:
+    strip_candidates = list(filter(bool, map(lambda x: remove_path_prefix(path, x), prefixes)))
+    return min(strip_candidates, key=len) if strip_candidates else path
+
 def make_include(state: State, file, include_str=None) -> Tuple[str, str]:
     if include_str is None:
-        include_str = file
+        include_str = make_include_strip_from_path(file, state.doxyfile['STRIP_FROM_INC_PATH']) if state.doxyfile['STRIP_FROM_INC_PATH'] is not None else file
 
     if file in state.includes and state.compounds[state.includes[file]].has_details:
         return (html.escape('<{}>'.format(include_str)), state.compounds[state.includes[file]].url)
@@ -3726,7 +3737,9 @@ def parse_doxyfile(state: State, doxyfile, values = None):
         'HTML_OUTPUT': ['html'],
         'DOT_FONTNAME': ['Helvetica'],
         'DOT_FONTSIZE': ['10'],
-        'SHOW_INCLUDE_FILES': ['YES']
+        'SHOW_INCLUDE_FILES': ['YES'],
+        'STRIP_FROM_PATH': [''],
+        'STRIP_FROM_INC_PATH': [''],
     }
 
     # Defaults so we don't fail with minimal Doxyfiles and also that the
@@ -3840,6 +3853,8 @@ def parse_doxyfile(state: State, doxyfile, values = None):
         ('INTERNAL_DOCS', None, bool),
         ('SHOW_INCLUDE_FILES', None, bool),
         ('TAGFILES', None, list),
+        ('STRIP_FROM_PATH', None, list),
+        ('STRIP_FROM_INC_PATH', None, list),
 
         ('M_THEME_COLOR', 'THEME_COLOR', str),
         ('M_FAVICON', 'FAVICON', str), # plus special handling below
@@ -3944,6 +3959,22 @@ def parse_doxyfile(state: State, doxyfile, values = None):
 
         state.config[alias] = navbar_links
 
+    # File paths extracted from <location file="loc"/> have already been
+    # stripped with respect to the Doxygen STRIP_FROM_PATH option. However, the
+    # make_include function needs to additionally strip any prefix present in
+    # STRIP_FROM_INC_PATH if present.
+    if state.doxyfile['STRIP_FROM_INC_PATH'] is not None:
+        all_prefixes = state.doxyfile['STRIP_FROM_INC_PATH']
+        # Add all the prefixes in STRIP_FROM_INC_PATH which have a common
+        # prefix with STRIP_FROM_PATH
+        for path_prefix in state.doxyfile['STRIP_FROM_PATH']:
+            # Construct the list of non empty suffixes of STRIP_FROM_INC_PATH
+            # for this STRIP_FROM_PATH prefix
+            from_path_strip = list(filter(bool, map(lambda x: remove_path_prefix(x, path_prefix), state.doxyfile['STRIP_FROM_INC_PATH'])))
+            all_prefixes += from_path_strip
+        # Remove duplicates
+        state.doxyfile['STRIP_FROM_INC_PATH'] = list(set(all_prefixes))
+
     # Below we finalize the config values, converting them to formats that are
     # easy to understand by the code / templates (but not easy to write from
     # the user PoV). If this is not a top-level call (but a recursed one from

diff --git a/documentation/test_doxygen/test_doxyfile.py b/documentation/test_doxygen/test_doxyfile.py
index 2f4d5de810c59a74a2c97311bcc7133d99218c42..022d1f25103f20e7749da4d8546e1942960b0069 100644 (file)
--- a/documentation/test_doxygen/test_doxyfile.py
+++ b/documentation/test_doxygen/test_doxyfile.py
@@ -50,6 +50,8 @@ class Doxyfile(unittest.TestCase):
         'PROJECT_LOGO': '',
         'PROJECT_NAME': 'My Pet Project',
         'SHOW_INCLUDE_FILES': True,
+        'STRIP_FROM_INC_PATH': [],
+        'STRIP_FROM_PATH': [],
         'XML_OUTPUT': 'xml'
     }
     expected_config = {