From 38ed1c4aa8e67f586e59dcf2fda23ca1d00f1e40 Mon Sep 17 00:00:00 2001
From: Alex Strick van Linschoten <stricksubscriptions@fastmail.fm>
Date: Mon, 24 Feb 2025 20:22:31 +0100
Subject: [PATCH] Fix SDK docs rendering with proper paths and directory
 structure

---
 docs/mkdocs.yml             |  7 ++++---
 docs/mkdocstrings_helper.py | 22 +++++++++++++++++-----
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index e39ac9afcb1..1bcc7f96dfa 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -20,11 +20,12 @@ plugins:
       handlers:
         python:
           setup_commands:
-            - import docs.sys_modules_mock           
+            - import docs.sys_modules_mock
           rendering:
             show_source: true
-      watch:
-        - ../src/zenml
+
+# This setting ensures links don't use directory URLs
+use_directory_urls: false
 
 copyright: >
   Copyright &copy; 2022 ZenML GmbH –
diff --git a/docs/mkdocstrings_helper.py b/docs/mkdocstrings_helper.py
index 9e32a7ed969..33ce4f0b92d 100644
--- a/docs/mkdocstrings_helper.py
+++ b/docs/mkdocstrings_helper.py
@@ -104,19 +104,24 @@ def create_entity_docs(
                 )
 
                 if md_prefix:
-                    file_name = md_prefix + "-" + item.stem
+                    # Create a directory for each module
+                    module_dir = api_doc_file_dir / f"{md_prefix}-{item.stem}"
+                    module_dir.mkdir(parents=True, exist_ok=True)
+                    file_name = "index"
                 else:
-                    file_name = item.stem
+                    module_dir = api_doc_file_dir / item.stem
+                    module_dir.mkdir(parents=True, exist_ok=True)
+                    file_name = "index"
                 to_md_file(
                     module_md,
                     file_name,
-                    out_path=api_doc_file_dir,
+                    out_path=module_dir,
                 )
 
                 if index_file_contents:
                     index_entry = (
                         f"# [{item_name}]"
-                        f"({API_DOCS}/{md_prefix}-{item.stem})\n\n"
+                        f"({API_DOCS}/{md_prefix}-{item.stem}/index.md)\n\n"
                         f"::: {zenml_import_path}.{item.stem}\n"
                         f"    handler: python\n"
                         f"    selection:\n"
@@ -196,7 +201,14 @@ def generate_docs(
         md_prefix="core",
     )
 
-    index_file_str = "\n".join(sorted(index_file_contents))
+    # Fix links in index file to point to index.md instead of just the directory
+    fixed_index_contents = []
+    for line in index_file_contents:
+        # Replace links with trailing slash to have index.md instead
+        line = line.replace(")/", ")/index.md")
+        fixed_index_contents.append(line)
+    
+    index_file_str = "\n".join(sorted(fixed_index_contents))
     to_md_file(
         index_file_str,
         "index.md",