General: Fix documentation and add markdown support (#41)

ls1intum · Feb 11, 2025 · 015140a · 015140a
1 parent cbd37e4
commit 015140a
Show file tree

Hide file tree

Showing 13 changed files with 91 additions and 76 deletions.
diff --git 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
@@ -0,0 +1,7 @@
+---
+title: "Admin Guide"
+---
+
+# Admin Guide
+
+General admin guide todo
diff --git a/docs/admin/admin.rst b/docs/admin/admin.rst
diff --git 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
@@ -0,0 +1,7 @@
+---
+title: "Developer Guide"
+---
+
+# Developer Guide
+
+General dev guide todo
diff --git a/docs/dev/dev.rst b/docs/dev/dev.rst
diff --git a/docs/dev/setup/setup.rst → docs/dev/setup/setup.md b/docs/dev/setup/setup.rst → 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.
diff --git a/docs/dev/system-design/system-design.rst → docs/dev/system-design/system-design.md b/docs/dev/system-design/system-design.rst → 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
diff --git a/docs/index.md 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
+```
diff --git a/docs/index.rst b/docs/index.rst
diff --git 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
diff --git a/docs/user/user.md b/docs/user/user.md
@@ -0,0 +1,7 @@
+---
+title: "User Guide"
+---
+
+# User Guide
+
+General user guide todo
diff --git a/docs/user/user.rst b/docs/user/user.rst