From 321e7ea6e19f2ef1e8ca5c14b412e89181135148 Mon Sep 17 00:00:00 2001
From: Chang Huan Lo <changhuan.lo@ucl.ac.uk>
Date: Wed, 18 Dec 2024 16:32:23 +0100
Subject: [PATCH] Refactor auto-generate `aeon_mecha` docs (#51)

---
 make_mecha_doctree.py             | 47 +++++++++++++------------------
 src/_templates/api_mecha_head.rst |  9 ++++--
 2 files changed, 25 insertions(+), 31 deletions(-)

diff --git a/make_mecha_doctree.py b/make_mecha_doctree.py
index 440415e4..0c5d440c 100644
--- a/make_mecha_doctree.py
+++ b/make_mecha_doctree.py
@@ -1,4 +1,6 @@
 import os
+from pathlib import Path
+
 
 # modules to ignore in the api doc
 ignore_modules = [
@@ -12,34 +14,23 @@ def make_mecha_doctree():
     Create a doctree of all modules in aeon_mecha/aeon.
     """
     doctree = ""
-    api_path = os.path.join(".", "aeon_mecha", "aeon")
-    for root, dirs, files in os.walk(api_path):
-        # remove leading "./"
-        root = root[2:]
-        for file in sorted(files):
-            if file.endswith(".py") and not file.startswith("_"):
-                # convert file path to module name
-                full = os.path.join(root, file)
-                full = full[:-3].replace(os.sep, ".")
-                full = (".").join(full.split(".")[1:])
-                ignore = False
-                for ignore_module in ignore_modules:
-                    if full.startswith(ignore_module):
-                        ignore = True
-                        break
-                if not ignore:
-                    doctree += f"    {full}\n"
-
-    # get the api doc header
-    with open("src/_templates/api_mecha_head.rst", "r") as f:
-        api_head = f.read()
-
-    # write file for api doc with header + doctree
-    output_dir = "./src/reference/api"
-    os.makedirs(output_dir, exist_ok=True)
-    
-    with open(os.path.join(output_dir, "mecha.rst"), "w") as f:
-        f.write("..\n  This file is auto-generated.\n\n")
+    api_path = Path("aeon_mecha") / "aeon"
+    for path in sorted(api_path.rglob("*.py")):
+        if path.name.startswith("_"):
+            continue
+        # Convert file path to module name
+        full = str(path.with_suffix("")).replace(os.sep, ".")
+        full = ".".join(full.split(".")[1:])
+        if not any(full.startswith(ignore_module) for ignore_module in ignore_modules):
+            doctree += f"   {full}\n"
+    # Get the main page header
+    api_head_path = Path("src") / "_templates" / "api_mecha_head.rst"
+    api_head = api_head_path.read_text()
+    # Write main page with header and doc tree
+    output_dir = Path("src") / "reference" / "api"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    output_file = output_dir / "mecha.rst"
+    with output_file.open("w") as f:
         f.write(api_head)
         f.write(doctree)
 
diff --git a/src/_templates/api_mecha_head.rst b/src/_templates/api_mecha_head.rst
index d5be4c18..6aac0783 100644
--- a/src/_templates/api_mecha_head.rst
+++ b/src/_templates/api_mecha_head.rst
@@ -1,12 +1,15 @@
+..
+  This file is auto-generated.
+
 .. _target-mecha-reference:
 
 ``aeon_mecha``
 ==============
 
 .. toctree::
-    :caption: aeon_mecha API
-    :maxdepth: 1
+   :caption: aeon_mecha API
+   :maxdepth: 1
 
 .. autosummary::
-    :toctree: mecha
+   :toctree: mecha