add docs (#78)

* add docs

* add some docs

docs/.gitignore

@@ -0,0 +1 @@
+.idea

docs/.readthedocs.yaml

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

docs/Dockerfile

@@ -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
+
+# use the autobuild as default command
+ENV SPHINXOPTS="--port 8000 --host 0.0.0.0"
+CMD exec make livehtml

docs/Makefile

@@ -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/_static/css/style.css

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

docs/conf.py

@@ -0,0 +1,60 @@
+# 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 = 'Aeolus'
+copyright = '2024, Technical University of Munich, Applied Software Engineering'
+author = 'Technical University of Munich, Applied Software Engineering'
+
+# -- 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"
+]
+
+# 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']
+
+# -- 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": "Aeolus",
+    "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/index.rst

@@ -0,0 +1,195 @@
+.. aeolus documentation master file, created by
+   sphinx-quickstart on Mon Feb 12 12:41:15 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to the documentation of aeolus!
+=======================================
+
+Aeolus is a Domain Specific Language (DSL) for defining continuous integration (CI) jobs in a declarative way.
+It is designed to be easy to use and to be able to define CI jobs for programming exercises that can be run on different CI platforms.
+
+.. toctree::
+   :maxdepth: 3
+   :caption: User Guide
+
+   user_guide/index
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Setup Guide
+
+   setup/index
+
+Features
+--------
+
+Currently, Aeolus can generate CI jobs for the following platforms:
+ - Bamboo
+ - Jenkins
+ - Bash Scripts (CLI)
+
+All three systems can be used with the same Aeolus configuration file, which makes it easy to switch between different CI platforms.
+The how and why we generate what we generate, is explained in the different target platform sections, see :ref:`targets`.
+An example for such a configuration file, we call in Windfile, looks like this:
+
+.. code-block:: yaml
+   :caption: Windfile that defines a simple CI job using Aeolus
+   :name: example-windfile
+
+   api: v0.0.1
+   metadata:
+     name: example windfile
+     id: example-windfile
+     description: This is a windfile with an internal action
+     author: Andreas Resch
+     docker:
+       image: ls1tum/artemis-maven-template
+       tag: java17-20
+   repositories:
+     aeolus:
+       url: https://github.com/ls1intum/Aeolus.git
+       branch: develop
+       path: aeolus
+   actions:
+     - name: script-action
+       script: echo "I am a script action"
+     - name: template-action
+       use: https://github.com/reschandreas/example-action.git
+       parameters:
+         WHO_TO_GREET: "hello"
+       environment:
+         HELLO: "world"
+
+With this single configuration, we generate the following CI jobs:
+
+***
+CLI
+***
+
+.. code-block:: sh
+   :caption: Bash script generated from the example windfile
+   :name: example-bash-script
+
+   #!/usr/bin/env bash
+   set -e
+   export AEOLUS_INITIAL_DIRECTORY=${PWD}
+   export REPOSITORY_URL="https://github.com/ls1intum/Aeolus.git"
+
+   scriptaction () {
+     echo '⚙️ executing scriptaction'
+     echo "I am a script action"
+   }
+
+   templateaction_ () {
+     local _current_lifecycle="${1}"
+     if [[ "${_current_lifecycle}" == "preparation" ]]; then
+       echo "⚙️ skipping templateaction_ because it is excluded during preparation"
+       return 0
+     fi
+
+     echo '⚙️ executing templateaction_'
+
+     export HELLO="world"
+     export WHO_TO_GREET="hello"
+       echo "Hello ${WHO_TO_GREET}"
+
+   }
+
+   main () {
+     if [[ "${1}" == "aeolus_sourcing" ]]; then
+       return 0 # just source to use the methods in the subshell, no execution
+     fi
+     local _current_lifecycle="${1}"
+
+     local _script_name
+     _script_name=${BASH_SOURCE[0]:-$0}
+     cd "${AEOLUS_INITIAL_DIRECTORY}"
+     bash -c "source ${_script_name} aeolus_sourcing; scriptaction \"${_current_lifecycle}\""
+     cd "${AEOLUS_INITIAL_DIRECTORY}"
+     bash -c "source ${_script_name} aeolus_sourcing; templateaction_ \"${_current_lifecycle}\""
+   }
+
+   main "${@}"
+
+
+*******
+Jenkins
+*******
+
+.. code-block:: groovy
+   :caption: Jenkinsfile generated from the example windfile
+   :name: example-jenkinsfile
+
+   pipeline {
+     agent {
+       docker {
+         image 'ls1tum/artemis-maven-template:java17-20'
+       }
+     }
+     parameters {
+       string(name: 'current_lifecycle', defaultValue: 'working_time', description: 'The current stage')
+     }
+     environment {
+       REPOSITORY_URL = 'https://github.com/ls1intum/Aeolus.git'
+     }
+
+     stages {
+       stage('aeolus') {
+         steps {
+           dir('aeolus') {
+             checkout([$class: 'GitSCM',
+               branches: [[name: 'develop']],
+               doGenerateSubmoduleConfigurations: false,
+               userRemoteConfigs: [[
+                 name: 'aeolus',
+                 url: "${REPOSITORY_URL}"
+               ]]
+             ])
+           }
+         }
+       }
+       stage('script-action') {
+         steps {
+           sh '''#!/usr/bin/env bash
+             echo "I am a script action"
+           '''
+         }
+       }
+       stage('template-action_0') {
+         when {
+           allOf {
+               expression { params.current_lifecycle != 'preparation' }
+           }
+         }
+         environment {
+           HELLO = 'world'
+           WHO_TO_GREET = 'hello'
+         }
+         steps {
+           sh '''#!/usr/bin/env bash
+             echo "Hello ${WHO_TO_GREET}"
+
+           '''
+         }
+       }
+     }
+   }
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Target Platforms
+   :name: targets
+
+   targets/bamboo/index
+   targets/jenkins/index
+   targets/cli/index
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.in

@@ -0,0 +1,5 @@
+# update with pip-compile requirements.in
+pip-tools
+Sphinx
+sphinx-rtd-theme
+sphinx-autobuild