add more docs

Author: reschandreas

docs/index.rst

@@ -9,6 +9,8 @@ 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.
 
+Check out our playground on `https://aeolus.artemis.cit.tum.de <https://aeolus.artemis.cit.tum.de>`_
+
 .. toctree::
    :maxdepth: 3
    :caption: User Guide
@@ -31,6 +33,7 @@ Currently, Aeolus can generate CI jobs for the following platforms:
 
 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

docs/setup/index.rst

@@ -81,4 +81,31 @@ Other Systems
 
 Seeing as Aeolus is meant to be a complementary tool to `Artemis <https://github.com/ls1intum/Artemis>`_, please refer to the Artemis documentation for more
 information on how to set up a local development environment for Artemis, including the documentation on how to set up
-`Jenkins <https://docs.artemis.cit.tum.de/dev/setup/jenkins-gitlab.html>`_ and `Bamboo <https://docs.artemis.cit.tum.de/dev/setup/bamboo-bitbucket-jira.html>`_ for local development.
+`Jenkins <https://docs.artemis.cit.tum.de/dev/setup/jenkins-gitlab.html>`_ and `Bamboo <https://docs.artemis.cit.tum.de/dev/setup/bamboo-bitbucket-jira.html>`_ for local development.
+
+
+++++++++++++++++
+Production Setup
+++++++++++++++++
+
+If you want to set up Aeolus in a production environment, you can use the provided Docker images and compose files.
+You can find the docker compose files in the ``deployment`` directory.
+
+If you choose to secure the API with a token, you also need to give Aeolus the following environment variables:
+
+.. code-block:: bash
+
+   AEOLUS_API_KEYS=<your-api-key>
+   # if you want to use jenkins as ci system
+   JENKINS_URL=<jenkins-url>
+   JENKINS_USERNAME=<jenkins-username>
+   JENKINS_TOKEN=<jenkins-password-of-the-user>
+
+   # if you want to use bamboo as ci system
+   BAMBOO_URL=<bamboo-url>
+   BAMBOO_USERNAME=<bamboo-username>
+   BAMBOO_TOKEN=<token-of-the-user>
+
+The ``AEOLUS_API_KEYS`` environment variable is a comma-separated list of API keys that are allowed to access the API.
+If you want to use the Jenkins or Bamboo generator, you also need to provide the respective environment variables.
+The key, if it is set, needs to be provided in the ``Authorization`` header of the request with the prefix ``Bearer``.

docs/targets/cli/index.rst

@@ -22,4 +22,49 @@ commands fail. This is useful to avoid the execution of the next commands if the
 the possibility to define actions that always need to be executed, regardless of the result of the previous commands.
 For this we use the `trap` command that captures the exit signal and executes the defined action. To also ensure that
 an `exit` command within an action does not break the script, we source the script instead of executing it and then execute
-the `main` function which spawns a subshell for each action.
+the `main` function which spawns a subshell for each action.
+
+One example of the script structure is shown below:
+
+.. code-block:: bash
+
+    #!/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 "${@}"

docs/targets/jenkins/index.rst

@@ -10,4 +10,61 @@ What does Aeolus generate?
 ++++++++++++++++++++++++++
 
 Aeolus generates a simple Jenkinsfile, that is then used in a simple pipeline. Each action from the input file is
-translated into a stage in the Jenkinsfile.
+translated into a stage in the Jenkinsfile. One example of a Jenkinsfile generated by Aeolus is:
+
+.. code-block:: groovy
+
+    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}"
+
+            '''
+          }
+        }
+      }
+    }