mkdocs fix

Author: Artur Huk

.github/workflows/docs.yml

@@ -16,6 +16,8 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: 3.x
+          python-version: '3.12'
+      - run: pip install -r requirements.txt
       - run: pip install -r requirements.mk.txt
+      - run: pip install -e .
       - run: mkdocs gh-deploy --force

mkdocs.yml

@@ -20,6 +20,7 @@ plugins:
   - mkdocstrings:
       handlers:
         python:
+          paths: [src]
           options:
             show_root_heading: true
             show_source: true

mkdocs_hooks.py

@@ -54,6 +54,20 @@ def on_page_markdown(markdown, page, config, **kwargs):
 
     if uri.startswith("09-pages/samples/"):
         markdown = markdown.replace("](../docs/", "](../")
+        
+        repo = (config.get("repo_url") or "").rstrip("/")
+        if repo:
+            def samples_repl(match: re.Match[str]) -> str:
+                rest = match.group(1)
+                head = rest.rstrip("/")
+                kind = "blob" if head.endswith((".md", ".py", ".yaml", ".sql", ".sh", ".cmd", ".example")) or "." in head.split("/")[-1] else "tree"
+                return f"]({repo}/{kind}/main/samples/{rest}"
+            
+            markdown = re.sub(r"\]\((?:\.\./)*(?:\./)?samples/([^)]+)\)", samples_repl, markdown)
+            # Also catch relative links that were rewritten by include-markdown plugin
+            # They usually look like ../../../samples/...
+            markdown = re.sub(r"\]\(\.\./\.\./\.\./samples/([^)]+)\)", samples_repl, markdown)
+
         if uri == "09-pages/samples/index.md":
             for d in _SAMPLE_READMES:
                 markdown = markdown.replace(f"]({d}/README.md)", f"]({d}.md)")