Documentation: replace relative image paths in Markdown image references with GitHub URLs

Author: TheMostDiligent

Doc/md_filter.py

@@ -3,11 +3,7 @@
 import re
 
 
-def compute_page_id(input_filepath):
-    # Determine the directory of this script.
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    # The project root is one level up.
-    root_dir = os.path.dirname(script_dir)
+def compute_page_id(root_dir, input_filepath):
     # Compute the file's absolute path and then its relative path from the root directory.
     abs_input_path = os.path.abspath(input_filepath)
     rel_path = os.path.relpath(abs_input_path, root_dir)
@@ -45,8 +41,63 @@ def replace_github_blob_urls(text):
     return re.sub(pattern, r'\1raw/\3', text)
 
 
+def replace_relative_image_paths(text, root_dir, input_filepath):
+    """
+    Replaces relative image paths in Markdown image references with GitHub URLs.
+
+    Markdown references of the form:
+      ![Alt Text](relative/image/path)
+    
+    are replaced as follows:
+    1. Compute the full relative path of the image with respect to the project root.
+       The project root is defined as one level up from the directory of this script.
+    2. If the first-level folder in the computed path starts with "Diligent", treat it as a submodule:
+         https://github.com/DiligentGraphics/<Submodule>/raw/master/<rest_of_path>
+       Otherwise, assume it belongs to the root module:
+         https://github.com/DiligentGraphics/raw/master/<computed_relative_path>
+    """
+    
+    # Regular expression to match Markdown image references.
+    pattern = r'!\[([^\]]*)\]\(([^)]+)\)'
+    
+    def repl(match):
+        alt_text = match.group(1)
+        image_path = match.group(2)
+        # If the path is already absolute (starts with "http"), leave it unchanged.
+        if image_path.startswith("http"):
+            return match.group(0)
+        
+        # Compute the full path of the image relative to the project root.
+        # The image path is relative to the input file location.
+        input_dir = os.path.dirname(os.path.abspath(input_filepath))
+        full_image_path = os.path.join(input_dir, image_path)
+        # Now compute the relative path from the project root.
+        relative_path = os.path.relpath(full_image_path, root_dir)
+        # Convert OS-specific path separators to forward slashes.
+        relative_path_url = relative_path.replace(os.sep, '/')
+        
+        # Split the path to check the first folder.
+        parts = relative_path_url.split('/')
+        if parts and parts[0].startswith("Diligent"):
+            module = parts[0]
+            rest = '/'.join(parts[1:])
+            new_url = f"https://github.com/DiligentGraphics/{module}/raw/master/{rest}"
+        else:
+            new_url = f"https://github.com/DiligentGraphics/raw/master/{relative_path_url}"
+        
+        return f"![{alt_text}]({new_url})"
+    
+    # Replace all Markdown image references in the text.
+    return re.sub(pattern, repl, text)
+
+
 def process_content(input_filepath, lines):
-    page_id = compute_page_id(input_filepath)
+    # Determine the directory of this script.
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    # The project root is one level up.
+    root_dir = os.path.dirname(script_dir)
+    
+    page_id = compute_page_id(root_dir, input_filepath)
     output_lines = []
     header_regex = re.compile(r'^\s*(#+)\s*(.+?)\s*$')
     header_replaced = False
@@ -58,6 +109,9 @@ def process_content(input_filepath, lines):
         # Fix image URLs.
         line = replace_github_blob_urls(line)
 
+        # Replace relative image paths in Markdown image references with GitHub URLs.
+        line = replace_relative_image_paths(line, root_dir, input_filepath)
+        
         # Look for the first non-empty line that starts with a Markdown header.
         if not header_replaced and line.strip():
             match = header_regex.match(line)