From c157e93011ccf78958812926f1eeef85488f4a8b Mon Sep 17 00:00:00 2001
From: Kevin Veen-Birkenbach <kevin@veen.world>
Date: Mon, 17 Mar 2025 12:05:39 +0100
Subject: [PATCH] Optimized Documentation about Sphinx and created Makefile in
 root

---
 04_SETUP.md                     |  2 +-
 Makefile                        | 12 ++++++++++++
 sphinx/README.md                | 25 +++++++++++++++++++++++++
 sphinx/templates/structure.html |  4 +++-
 4 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 Makefile
 create mode 100644 sphinx/README.md

diff --git a/04_SETUP.md b/04_SETUP.md
index 17acf6eb..78ec7903 100644
--- a/04_SETUP.md
+++ b/04_SETUP.md
@@ -93,7 +93,7 @@ ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)pl
 
 ---
 
-## Using a Vault Password File
+## Using a Password File
 
 To avoid entering your vault password interactively every time, use the `--vault-password-file` option:
 ```bash
diff --git a/Makefile b/Makefile
new file mode 100644
index 00000000..fb1e565c
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,12 @@
+.PHONY: install deinstall refresh
+
+install:
+	$(MAKE) -C sphinx html
+	$(MAKE) -C sphinx install
+
+deinstall:
+	$(MAKE) -C sphinx clean
+
+refresh:
+	$(MAKE) -C sphinx clean
+	$(MAKE) -C sphinx html
diff --git a/sphinx/README.md b/sphinx/README.md
new file mode 100644
index 00000000..e47b31b1
--- /dev/null
+++ b/sphinx/README.md
@@ -0,0 +1,25 @@
+# Documentation
+
+CyMaIS uses [Sphinx](https://www.sphinx-doc.org/) to automatically generate its documentation and leverages the [Awesome Sphinx Theme](https://sphinxawesome.xyz/) for a sleek and responsive design. Enjoy a seamless, visually engaging experience 🚀✨.
+
+## For Users
+
+You can access the documentation [here](https://docs.cymais.cloud/) 🔗. Browse the latest updates and guides to get started.
+
+## For Administrators
+
+### Setup
+
+#### On Localhost
+
+To generate the documentation locally, run the following command:
+
+```bash
+pkgmgr shell cymais -c "make refresh"
+```
+
+This command cleans the previous build and generates the updated documentation. Once complete, you can view it at the output location (e.g., [templates/html/index.html](templates/html/index.html)) 👀💻.
+
+#### On Server
+
+In your inventory file, enable the **Sphinx** role. When activated, the documentation will be automatically generated and deployed under the **docs** subdomain of your CyMaIS instance. This ensures your documentation is always current and easily accessible 🔄🌐.
\ No newline at end of file
diff --git a/sphinx/templates/structure.html b/sphinx/templates/structure.html
index f8337fe6..c9b55b5f 100644
--- a/sphinx/templates/structure.html
+++ b/sphinx/templates/structure.html
@@ -40,10 +40,12 @@
 
 {% if local_md_headings or local_subfolders %}
 <div class="local-md-headings">
-  <h3 class="toctree-l1">Index</h3>
+  <h3>Overview</h3>
+  <h4 class="toctree-l1">Current Index</h3>
   {% if local_md_headings %}
     {{ render_headings(local_md_headings) }}
   {% endif %}
+  <h4 class="toctree-l1">File Explorer</h3>
   {% if local_subfolders %}
     {{ render_headings(local_subfolders) }}
   {% endif %}