Development: Add template for documentation (#6)

Author: MaximilianAnzinger

.idea/.gitignore

@@ -0,0 +1,6 @@
+_build/
+.venv/
+.idea/
+__pycache__/
+.env
+venv

docs/.gitignore

@@ -0,0 +1,12 @@
+---
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+sphinx:
+  fail_on_warning: true
+python:
+  install:
+    - requirements: docs/requirements.txt

docs/.readthedocs.yaml

@@ -0,0 +1,15 @@
+FROM sphinxdoc/sphinx
+
+WORKDIR /docs
+# create non-root user to be able to edit the generated files without root access later
+RUN groupadd -g 1000 sphinx-user \
+    && useradd -ms /bin/bash -u 1000 -g 1000 sphinx-user \
+    && chown 1000:1000 /docs
+ADD requirements.txt /docs
+RUN pip3 install -r requirements.txt
+
+USER sphinx-user
+EXPOSE 8000
+# use the autobuild as default command
+ENV SPHINXOPTS="--port 8000 --host 0.0.0.0"
+CMD exec make livehtml

docs/Dockerfile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+# -W: treat warnings as errors
+SPHINXOPTS    ?= -W
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,163 @@
+# Atlas Documentation
+
+We use [Sphinx] for creating the Atlas documentation using [reStructuredText] (RST).
+To get started with RST, check out the [Quickstart] or this [cheatsheet].
+
+Please document the features that you have developed as **extensive as possible** from the user perspective, because the documentation also serves as a **user manual**. This is really important so that users can better understand how to use Atlas.
+
+Creating a user manual for a service such as Atlas can be a bit of a juggling act, especially when it's for students. Here are some best practices that should help:
+
+## Best Practices
+1. Atlas documentation must use **realistic examples** and personas and must avoid the use of test data. 
+
+2. **Keep it simple and user-friendly**: Remember, you're writing for end-users, not just fellow tech enthusiasts. Use plain language, avoid jargon, and explain technical terms when they can't be avoided.
+
+3. **Use visual aids**: Screenshots, diagrams, and even short video tutorials can be a lot more effective than pages of text. They make it easier for students to understand and follow instructions
+
+4. **Structure it intuitively**: Organize the content in a logical flow. Start with basic functions before moving to more advanced features. Think about how a student would use the system and structure your documentation accordingly.
+
+5. **Include a searchable FAQ section**: Let's face it, not everyone is going to read the documentation cover-to-cover. A FAQ section for common issues or questions can be a lifesaver
+
+6. **Apply accessible and inclusive design**: Make sure your documentation is accessible to all students, including those with disabilities. Use clear fonts, alt text for images, and consider a screen-reader-friendly version.
+
+7. **Update regularly**: Atlas evolves, and so should the documentation. Keep it up-to-date with any changes in the system.
+
+8. **Create a feedback loop**: Encourage users to give feedback on the documentation. They might point out confusing sections or missing information that you hadn't considered.
+
+9. **Use familiar information**: This is crucial in the documentation because it simplifies the learning process for new users. Real-world scenarios demonstrate to users how to apply specific features within their own context, whereas test data can mislead and fails to reflect real use cases. Realistic examples and personas provide clarity and relevance, ensuring users can effectively understand and utilize Atlas.
+
+10. **Use well defined personas**: Personas are vital for the development process, they do not only help readers to understand the documentation, but also allow developers to better understand Atlas and its users. Many organizations use personas, the two blog posts below contain additional introduction and motivation for the topic:
+- [Using Personas During Design and Documentation](https://www.uxmatters.com/mt/archives/2010/10/using-personas-during-design-and-documentation.php)
+- [Customer Personas: How to Write Them and Why You Need Them in Agile Software Development](https://community.atlassian.com/t5/App-Central/Customer-Personas-How-to-Write-Them-and-Why-You-Need-Them-in/ba-p/759228)
+
+11. **Use realistic data**: Screenshots and screencasts included in Atlas documentation **must** present **realistic data**. That includes but is not limited to:
+   - realistic user, course and competency names
+   - realistic text passages, like competency titles and descriptions  
+
+12. **Avoid test data**: Screenshots and screencasts included in Atlas documentation **must not** present any test data or server information. That includes but is not limited to:
+   - `Test Server` and `Development` labels
+   - test user, course and resource names
+   - _Lorem ipsum_ and mock text passages, like submissions contents and problem statements 
+   - test server and `localhost` domains
+
+13. **Keep screencasts short**: Cut them to at most two minutes to keep the documentation simple and easy to navigate. If you have larger ones, please split them into small screencasts based on the user workflow or features that you describe. Embed videos using TUM.Live and do **not** host them on Youtube (to avoid advertisement and data privacy issues).
+
+
+
+
+
+## Documentation Hosting
+
+[Read the Docs] (RtD) hosts the [Atlas documentation] for the `develop` (latest) branch, as well as for
+git tags and branches of pull requests.
+You can switch the shown version at the bottom of the sidebar.
+The latest tag is always the _stable_ version.
+For pull requests, the documentation is available at `https://atlas-platform--{PR_NUMBER}.org.readthedocs.build/en/{PR_NUMBER}/`.
+RtD will build and deploy changes automatically.
+
+## Installing Sphinx Locally
+
+Optionally, create and activate a virtual environment:
+```
+python3 -m venv venv
+```
+On Linux or macOS:
+```
+source venv/bin/activate
+```
+On Windows (CMD):
+```
+venv\Scripts\activate.bat
+```
+On Windows (PowerShell):
+```
+venv\Scripts\Activate.ps1
+```
+
+
+[Sphinx] can run locally to generate the documentation in HTML and other formats.
+You can install Sphinx using `pip` or choose a system-wide installation instead.
+When using pip, consider using [Python virtual environments].
+```bash
+pip install -r requirements.txt
+```
+or
+```bash
+pip3 install -r requirements.txt
+```
+The [Installing Sphinx] documentation explains more install options.
+For macOS, it is recommended to install it using homebrew:
+```bash
+brew install sphinx-doc
+brew link sphinx-doc --force
+pip3 install -r requirements.txt
+```
+
+## Running Sphinx Locally
+
+To generate the documentation as a single HTML file, use the provided `Makefile`/`make.bat` files in the folder `docs`:
+```bash
+# maxOS / Linux
+make singlehtml
+
+# Windows
+make.bat singlehtml
+```
+
+
+Using [sphinx-autobuild], the browser will live-reload on changes, ideal for viewing changes while writing documentation:
+```bash
+# maxOS / Linux
+make livehtml
+
+# Windows
+make.bat livehtml
+```
+
+## Running Sphinx Locally with Docker
+
+To generate the documentation as an HTML file, use the provided docker command from the project root:
+```bash
+docker run --rm -v ${PWD}/docs:/docs $(docker build -q -t sphinx -f docs/Dockerfile ./docs) make singlehtml
+```
+
+To auto-generate the documentation as HTML file and live-reload on changes,
+use the provided docker command from the project root:
+```bash
+docker run --rm -it -v ${PWD}/docs:/docs -p 8000:8000 $(docker build -q -t sphinx -f docs/Dockerfile ./docs)
+```
+
+## Tool support
+A list of useful tools to write documentation:
+- [reStructuredText for Visual Studio Code](https://www.restructuredtext.net)
+- [LanguageTool for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=adamvoss.vscode-languagetool): Provides offline grammar checking
+- [ReStructuredText for IntelliJ](https://plugins.jetbrains.com/plugin/7124-restructuredtext)
+
+
+
+<!-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -->
+[Atlas documentation]: https://atlas-platform.readthedocs.io
+
+[reStructuredText]: https://docutils.sourceforge.io/rst.html
+[Quickstart]: https://docutils.sourceforge.io/docs/user/rst/quickstart.html
+[cheatsheet]: http://github.com/ralsina/rst-cheatsheet/raw/master/rst-cheatsheet.pdf
+
+[Sphinx]: https://www.sphinx-doc.org/en/master/
+[Installing Sphinx]: https://www.sphinx-doc.org/en/master/usage/installation.html
+[Python virtual environments]: https://docs.python.org/3/library/venv.html
+[sphinx-autobuild]: https://pypi.org/project/sphinx-autobuild/
+[Read the Docs]: https://readthedocs.org
+
+
+### Dependency management
+
+Find outdated dependencies using the following command:
+```
+pip list --outdated
+```
+
+Find unused dependencies using the following command:
+```
+pip install deptry
+deptry .
+```

docs/README.md

@@ -0,0 +1,6 @@
+/* This import resolves when built */
+@import url("theme.css");
+
+.wy-body-for-nav .wy-nav-content {
+    max-width: none;
+}

docs/_static/css/style.css

@@ -0,0 +1,6 @@
+.. _admin:
+
+Admin Guide
+================
+
+General admin guide todo

docs/admin/admin.rst

@@ -0,0 +1,78 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Atlas'
+copyright = '2024, Technical University of Munich, Applied Education Technologies'
+author = 'Technical University of Munich, Applied Education Technologies'
+
+
+# -- General configuration ---------------------------------------------------
+
+# The document name of the “main” document, that is, the document
+# that contains the root toctree directive.
+master_doc = "index"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinxcontrib.bibtex"
+]
+
+# 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']
+
+linkcheck_ignore = [
+    r'http(s)?://.*localhost(:\d+)?/?',
+]
+# do not check anchors on websites that need JavaScript to load the content
+# the anchor points to
+linkcheck_anchors_ignore_for_url = [
+    r"https://angular.io/guide/.*",
+    r"https://github.com/.*",
+    r"https://k3d.io/.*"
+]
+
+# -- Publications ------------------------------------------------------------
+bibtex_bibfiles = ['research/publications.bib']
+bibtex_default_style = 'unsrtalpha'
+bibtex_reference_style = 'label'
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+html_context = {
+    "display_github": True,
+    "github_user": "ls1intum",
+    "github_repo": "Atlas",
+    "github_version": "develop",
+    "conf_py_path": "/docs/",
+}
+html_style = 'css/style.css'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/conf.py

@@ -0,0 +1,6 @@
+.. _dev:
+
+Developer Guide
+================
+
+General dev guide todo