[Docs] Enable relative links in examples to function when rendered in the docs (#24041)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
This commit is contained in:
Harry Mellor
2025-09-10 05:40:45 +01:00
committed by GitHub
parent 4377b1ae3b
commit e40827280b

View File

@ -114,6 +114,33 @@ class Example:
return match.group('title')
return fix_case(self.path.stem.replace("_", " ").title())
def fix_relative_links(self, content: str) -> str:
"""
Fix relative links in markdown content by converting them to gh-file
format.
Args:
content (str): The markdown content to process
Returns:
str: Content with relative links converted to gh-file format
"""
# Regex to match markdown links [text](relative_path)
# This matches links that don't start with http, https, ftp, or #
link_pattern = r'\[([^\]]*)\]\((?!(?:https?|ftp)://|#)([^)]+)\)'
def replace_link(match):
link_text = match.group(1)
relative_path = match.group(2)
# Make relative to repo root
gh_file = (self.main_file.parent / relative_path).resolve()
gh_file = gh_file.relative_to(ROOT_DIR)
return f'[{link_text}](gh-file:{gh_file})'
return re.sub(link_pattern, replace_link, content)
def generate(self) -> str:
content = f"# {self.title}\n\n"
content += f"Source <gh-file:{self.path.relative_to(ROOT_DIR)}>.\n\n"
@ -121,14 +148,16 @@ class Example:
# Use long code fence to avoid issues with
# included files containing code fences too
code_fence = "``````"
# Skip the title from md snippets as it's been included above
start_line = 2
if self.is_code:
content += f"{code_fence}{self.main_file.suffix[1:]}\n"
start_line = 1
content += f'--8<-- "{self.main_file}:{start_line}"\n'
if self.is_code:
content += f"{code_fence}\n"
content += (f"{code_fence}{self.main_file.suffix[1:]}\n"
f'--8<-- "{self.main_file}"\n'
f"{code_fence}\n")
else:
with open(self.main_file) as f:
# Skip the title from md snippets as it's been included above
main_content = f.readlines()[1:]
content += self.fix_relative_links("".join(main_content))
content += "\n"
if not self.other_files: