From e4869e0061fe2a169c33149f67b83a8ce0e093bd Mon Sep 17 00:00:00 2001
From: Tibo De Peuter <tibo.depeuter@ugent.be>
Date: Tue, 19 May 2026 22:58:01 +0200
Subject: [PATCH] docs: fix non docs/ links

---
 .github/scripts/prepare_docs.py    | 35 ++++++++++++++++++++++++++++++
 .github/workflows/publish-docs.yml |  3 +++
 docs/CONTRIBUTING.md               |  2 +-
 docs/README.md                     |  2 +-
 4 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 .github/scripts/prepare_docs.py

diff --git a/.github/scripts/prepare_docs.py b/.github/scripts/prepare_docs.py
new file mode 100644
index 0000000..bc3a47d
--- /dev/null
+++ b/.github/scripts/prepare_docs.py
@@ -0,0 +1,35 @@
+import os
+import glob
+import re
+import shutil
+
+folders_to_copy = ['src', 'scripts']
+for folder in folders_to_copy:
+    if os.path.exists(folder):
+        shutil.copytree(folder, f'docs/{folder}', dirs_exist_ok=True)
+
+for filepath in glob.glob('docs/**/*.md', recursive=True):
+    with open(filepath, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    # RULE A: Fix links pointing OUT to src/ or scripts/ 
+    # Logic: Because the folders were moved one level deeper, we remove exactly ONE '../'
+    content = re.sub(
+        r'\]\(\.\./((?:\.\./)*)(src|scripts)/([^)]*)\)', 
+        r'](\1\2/\3)', 
+        content
+    )
+
+    # RULE B: Fix links pointing FROM the copied files back TO the original docs/ folder
+    # Logic: Since these files are now inside docs/, the 'docs/' segment in the path is redundant.
+    content = re.sub(
+        r'\]\(((?:\.\./)+)docs/([^)]*)\)', 
+        r'](\1\2)', 
+        content
+    )
+
+    with open(filepath, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+print("Successfully imported external files and adjusted markdown links.")
+
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
index 177e04d..668c977 100644
--- a/.github/workflows/publish-docs.yml
+++ b/.github/workflows/publish-docs.yml
@@ -26,6 +26,9 @@ jobs:
       - name: Install dependencies
         run: pip install mkdocs-material
 
+      - name: Prepare external docs
+        run: python .github/scripts/prepare_docs.py
+
       - name: Configure Git identity
         run: |
           git config --global user.name "github-actions[bot]"
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index bd58706..5903790 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Code readability is paramount, as code is read far more frequently than it is wr
 
 * **Git Practices:** Commits must be frequent and small. Each commit should relate to exactly one piece of functionality.
 * **Branching Strategy:** The `dev` branch serves as the integration branch for pushing and merging code. Only stable releases may be pushed to the `main` branch.
-* **Artifact Management:** Data files, trained models, and large datasets must never be committed directly to Git. Git Large File Storage (LFS) must be used for tracking large files. **All developers must have `git-lfs` installed locally** (see `DEVELOPMENT.md` for setup).
+* **Artifact Management:** Data files, trained models, and large datasets must never be committed directly to Git. Git Large File Storage (LFS) must be used for tracking large files. **All developers must have `git-lfs` installed locally** (see [DEVELOPMENT.md](./DEVELOPMENT.md) for setup).
 * **Repository Layout:** The repository must maintain the following core directories: `src/` for algorithms, `env/` for MuJoCo wrappers, `config/` for experiment configurations, `experiments/` for scripts, `docs/` for Doxygen or ReadTheDocs documentation, and `tests/` for unit tests.
 
 ## 4. Architecture & Tooling
diff --git a/docs/README.md b/docs/README.md
index 521cb28..237a1a5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,7 +9,7 @@ If you are interested in the "why did you do it like this?"
 - [Controllers](./design/controllers.md): Macroscopig brain toplogy, centralized, arm-level, segment-level.
 - [Input/output](./design/input_action_spaces.md): Description of the model's input and output.
 - [Learning algorithm](./design/learning_algorithm.md): RL techniques, i.e. PPO.
-- [Reward function](./design/learning_algorithm.md): Goals, fitness tracking, and reward structures.
+- [Reward function](./design/reward_function.md): Goals, fitness tracking, and reward structures.
 
 ## API reference (`/api`)