From 015140acfc683918fea258f2119f4dd385b5dbc1 Mon Sep 17 00:00:00 2001
From: Maximilian Anzinger
 <44003963+MaximilianAnzinger@users.noreply.github.com>
Date: Tue, 11 Feb 2025 16:39:57 +0100
Subject: [PATCH] General: Fix documentation and add markdown support (#41)

---
 docs/.readthedocs.yaml                        |  1 +
 docs/admin/admin.md                           |  7 ++++
 docs/admin/admin.rst                          |  6 ----
 docs/conf.py                                  | 13 +++++--
 docs/dev/dev.md                               |  7 ++++
 docs/dev/dev.rst                              |  6 ----
 docs/dev/setup/{setup.rst => setup.md}        |  7 ++--
 .../{system-design.rst => system-design.md}   | 20 +++++------
 docs/index.md                                 | 36 +++++++++++++++++++
 docs/index.rst                                | 34 ------------------
 docs/requirements.txt                         | 17 +++++----
 docs/user/user.md                             |  7 ++++
 docs/user/user.rst                            |  6 ----
 13 files changed, 91 insertions(+), 76 deletions(-)
 create mode 100644 docs/admin/admin.md
 delete mode 100644 docs/admin/admin.rst
 create mode 100644 docs/dev/dev.md
 delete mode 100644 docs/dev/dev.rst
 rename docs/dev/setup/{setup.rst => setup.md} (76%)
 rename docs/dev/system-design/{system-design.rst => system-design.md} (62%)
 create mode 100644 docs/index.md
 delete mode 100644 docs/index.rst
 create mode 100644 docs/user/user.md
 delete mode 100644 docs/user/user.rst

diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml
index 4e14204..0c7b282 100644
--- a/docs/.readthedocs.yaml
+++ b/docs/.readthedocs.yaml
@@ -6,6 +6,7 @@ build:
   tools:
     python: "3.12"
 sphinx:
+  configuration: docs/conf.py
   fail_on_warning: true
 python:
   install:
diff --git a/docs/admin/admin.md b/docs/admin/admin.md
new file mode 100644
index 0000000..3731883
--- /dev/null
+++ b/docs/admin/admin.md
@@ -0,0 +1,7 @@
+---
+title: "Admin Guide"
+---
+
+# Admin Guide
+
+General admin guide todo
\ No newline at end of file
diff --git a/docs/admin/admin.rst b/docs/admin/admin.rst
deleted file mode 100644
index d09db37..0000000
--- a/docs/admin/admin.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. _admin:
-
-Admin Guide
-===========
-
-General admin guide todo
diff --git a/docs/conf.py b/docs/conf.py
index 4b20a7f..0fd9c03 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Atlas'
-copyright = '2024, Technical University of Munich, Applied Education Technologies'
+copyright = '2025, Technical University of Munich, Applied Education Technologies'
 author = 'Technical University of Munich, Applied Education Technologies'
 
 
@@ -33,13 +33,20 @@
 # ones.
 extensions = [
     "sphinx_rtd_theme",
-    "sphinxcontrib.bibtex"
+    "sphinxcontrib.bibtex",
+    "myst_parser"
 ]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv', 'README.md', 'requirements.txt']
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
 
 linkcheck_ignore = [
     r'http(s)?://.*localhost(:\d+)?/?',
diff --git a/docs/dev/dev.md b/docs/dev/dev.md
new file mode 100644
index 0000000..c7727a6
--- /dev/null
+++ b/docs/dev/dev.md
@@ -0,0 +1,7 @@
+---
+title: "Developer Guide"
+---
+
+# Developer Guide
+
+General dev guide todo
\ No newline at end of file
diff --git a/docs/dev/dev.rst b/docs/dev/dev.rst
deleted file mode 100644
index d16ef45..0000000
--- a/docs/dev/dev.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. _dev:
-
-Developer Guide
-===============
-
-General dev guide todo
\ No newline at end of file
diff --git a/docs/dev/setup/setup.rst b/docs/dev/setup/setup.md
similarity index 76%
rename from docs/dev/setup/setup.rst
rename to docs/dev/setup/setup.md
index 9f5bad1..cf493d0 100644
--- a/docs/dev/setup/setup.rst
+++ b/docs/dev/setup/setup.md
@@ -1,7 +1,8 @@
-.. _dev_setup:
+---
+title: "Setup Guide"
+---
 
-Setup Guide
-===========
+# Setup Guide
 
 Setting up Atlas in your development environment or a demo production environment is really easy following
 the instructions on this page.
\ No newline at end of file
diff --git a/docs/dev/system-design/system-design.rst b/docs/dev/system-design/system-design.md
similarity index 62%
rename from docs/dev/system-design/system-design.rst
rename to docs/dev/system-design/system-design.md
index 471584a..9aa25ae 100644
--- a/docs/dev/system-design/system-design.rst
+++ b/docs/dev/system-design/system-design.md
@@ -1,23 +1,21 @@
-*************
-System Design
-*************
+---
+title: "System Design"
+---
 
-Top-Level Design
-================
+# System Design
+
+## Top-Level Design
 
 The following diagram shows the top-level design of Atlas which is decomposed into the AtlasML server application that provides the REST API that learning management systems can connect to to integrate competency based learning into their systems.
 
-Deployment
-==========
+## Deployment
 
 TODO
 
-Data Model
-==========
+## Data Model
 
 TODO
 
-Server Architecture
-===================
+## Server Architecture
 
 TODO
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..1424712
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,36 @@
+---
+title: "Atlas: Competency Based Learning Management System"
+---
+
+# Atlas: Competency Based Learning Management System
+
+## Main features
+
+Atlas main features
+
+```{toctree}
+:caption: User Guide
+:includehidden:
+:maxdepth: 3
+
+user/user
+```
+
+```{toctree}
+:caption: Contributor Guide
+:includehidden:
+:maxdepth: 3
+
+dev/dev
+dev/development-process/development-process
+dev/system-design/system-design
+dev/setup/setup
+```
+
+```{toctree}
+:caption: Administration Guide
+:includehidden:
+:maxdepth: 3
+
+admin/admin
+```
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644
index 43e1416..0000000
--- a/docs/index.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-.. _atlas:
-
-==================================================
-Atlas: Competency Based Learning Management System
-==================================================
-
-Main features
--------------
-
-Atlas main features
-
-.. toctree::
-   :caption: User Guide
-   :includehidden:
-   :maxdepth: 3
-
-   user/user
-
-.. toctree::
-   :caption: Contributor Guide
-   :includehidden:
-   :maxdepth: 3
-
-   dev/dev
-   dev/development-process/development-process
-   dev/system-design/system-design
-   dev/setup/setup
-
-.. toctree::
-   :caption: Administration Guide
-   :includehidden:
-   :maxdepth: 3
-
-   admin/admin
diff --git a/docs/requirements.txt b/docs/requirements.txt
index fdf26e7..fc1e495 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,8 +1,11 @@
-Sphinx==7.4.7
-sphinx-rtd-theme==2.0.0
-sphinx-autobuild==2024.9.19
-sphinxcontrib-bibtex==2.6.3
+alabaster==1.0.0
+docutils==0.21.2
+Jinja2==3.1.5
 requests==2.32.3
-zipp==3.20.2
-docutils==0.20.1
-urllib3==2.2.3
+Sphinx==8.1.3
+sphinx-rtd-theme==3.0.2
+sphinx-autobuild==2024.10.3
+sphinxcontrib-bibtex==2.6.3
+urllib3==2.3.0
+zipp==3.21.0
+myst_parser==4.0.0
\ No newline at end of file
diff --git a/docs/user/user.md b/docs/user/user.md
new file mode 100644
index 0000000..73e69be
--- /dev/null
+++ b/docs/user/user.md
@@ -0,0 +1,7 @@
+---
+title: "User Guide"
+---
+
+# User Guide
+
+General user guide todo
\ No newline at end of file
diff --git a/docs/user/user.rst b/docs/user/user.rst
deleted file mode 100644
index 40090df..0000000
--- a/docs/user/user.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-.. _user:
-
-User Guide
-==========
-
-General user guide todo