refactor(docs): dev-guide: write machine setup

docs/developers-guide/machine-setup.md

+# Machine Setup
+
+## General
+
+### Git
+
+The whole project is a Git repository,
+to do anything you'll need to have Git setup on your machine.
+
+!!! tip
+    We highly recommend you use Git directly typing commands to your terminal,
+    instead of relying on any GUI tools, IDE integration's whatsoever.
+    They make life easy, sure.
+    But do you know, what exact calls they do under the hood?
+
+#### Installation
+
+=== "*nix"
+    Should be part of all major systems default software distribution path.
+
+=== "Windows"
+    !!! warning "disclaimer"
+        This is for people having not much experience.
+        If you e.g. use Cygwin, you could just install Git from there and ignore this^^
+
+    - Download Git: [Git-SCM][gitscm-win]
+    - Installation recommendations:
+        - opt-out from `Enable Git Credential Manager`  
+            _We had bad experiences with it, storing wrong passwords an no one knew where to remove them as none of the pros used this thing^^_
+
+#### Configuration
+
+After installing Git, you'll have to set a few information,
+in order to be able to work with it.
+Mandatory is your username and email.
+
+Globally set your most used username and email address you'll be using.
+
+```bash
+git config --global user.name "<username>"
+git config --global user.email "<email address>"
+```
+
+!!! attention
+    If your global email is different from the one for this projects GitLab,
+    make sure to either add your main email address as committer email in your profile,
+    or change the git config for this project individually after cloning it.
+
+#### Clone project
+
+As of writing, the project can be accessed with HTTPS and SSH.
+If this is not working,
+check the repository from the link in the upper right corner of the page.
+(Maybe the path changed and someone forgot to update this part of the docs)
+
+=== "SSH"
+    ```bash
+    git clone git@transfer.hft-stuttgart.de:9Lukas5/unified-ticketing.git
+    ```
+
+=== "HTTPS"
+    ```bash
+    git clone https://transfer.hft-stuttgart.de/gitlab/9Lukas5/unified-ticketing.git
+    ```
+
+## Java Development
+
+The Java library is development with OpenJDK 8 and Maven 3.6
+
+### Requirements
+
+- Git setup
+- OpenJDK 1.8.0+
+- Maven 3.6.0+
+
+### Installation
+
+#### OpenJDK
+
+=== "*nix"
+    Check your specific systems package names.
+
+    __Ubuntu 20.04__:  
+    ```bash
+    sudo apt install openjdk-11-jdk
+    ```
+
+=== "Windows"
+
+    - download OpenJDK: [jdk.java.net][java-net]
+    - extract archive to permanent place
+    - create/update system environment variable `JAVA_HOME`,
+        to the path you extracted OpenJDK to.
+    - update `PATH` variable including the `bin` folder of your newly placed OpenJDK
+    - check with a terminal that `java --version` works
+
+#### Maven
+
+=== "*nix"
+    Same as before, check your specific systems package names.
+
+    __Ubuntu:__  
+    ```bash
+    sudo apt install maven
+    ```
+
+=== "Windows"
+
+    - download Maven binary: [maven.apache.org][maven-dl]
+    - extract archive to permanent place
+    - create/update system environment variable `MAVEN_HOME`,
+        to the path you extracted Maven to.
+    - update `PATH` including `bin` folder of maven home
+    - check that `mvn --version` works
+
+### Import project to IDE
+
+Following is described, how to import the maven project to your IDE.
+I really hope, you're familiar enough to know how to use your IDE,
+so this is a just-in-case service.
+
+Also, this does not claim to be up-to-date/correct/cover all available IDE's.
+You are invited to contribute to this list below
+if you're IDE of choice is not listed yet or has some faults.
+
+=== "IntelliJ IDEA"
+    - Select `Open or Import`
+    - Choose the folder you cloned the project into
+
+## MkDocs (Documentation)
+
+This project is documented using MkDocs Material.
+It means we write Markdown files, organize them in a configuration file
+and MkDocs generates a static Website out of it we host and you are reading right now.
+
+### Requirements
+
+- Python 3.5+
+- pip
+- Python virtual environment _(optional)_
+
+### Installation
+
+=== "*nix"
+    check system specific names and commands, below are some examples collected over time:
+
+    __Ubuntu:__  
+    ```bash
+    sudo apt install python3 python3-pip python3-venv
+    ```
+
+=== "Windows"
+    - download & install Python: [python.org][python-win-dl] (use executable installer version)
+
+- open a terminal inside the project's root directory
+- _optional:_ create & activate new virtual environment:
+
+    === "*unix"
+        ```bash
+        python3 -m venv env
+        . ./env/bin/activate
+        ```
+
+    === "Windows"
+        === "CMD"
+            ```cmd
+            python -m venv env
+            env\scripts\activate.bat
+            ```
+        === "Power Shell"
+            !!! attention "execution policy"
+                You may have to first set the correct execution policy,
+                before able to run the activation script.
+
+                ```powershell
+                Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+                ```
+
+            ```powershell
+            python -m venv env
+            env\scripts\Activate.ps1
+            ```
+
+- install all required packages:  
+    ```
+    pip install -Ur requirements.txt
+    ```
+
+### Usage
+
+To work on the documentation, the mkdocs development server has to run.
+On start it tells you on which port it runs (default is `8000`).
+
+Open the Browser on the shown URL and edit the Markdown files.
+On saving changes your Browser should automatically reload the page.
+
+- _optional:_ enter python virtual environment
+
+    === "*unix"
+        ```bash
+        . ./env/bin/activate
+        ```
+
+    === "Windows"
+        === "CMD"
+            ```cmd
+            env\scripts\activate.bat
+            ```
+        === "Power Shell"
+            !!! attention "execution policy"
+                You may have to first set the correct execution policy,
+                before able to run the activation script.
+
+                ```powershell
+                Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+                ```
+
+            ```powershell
+            env\scripts\Activate.ps1
+            ```
+
+- start MkDocs development server:  
+    ```bash
+    mkdocs serve
+    ```
+- work
+- kill dev server by pressing `ctrl+c`
+- _optional:_ exit python virtual environment:  
+    ```bash
+    deactivate
+    ```
+
+### Editor/IDE
+
+You don't need any special IDE, as a bare minimum a text editor would work (even vim is possible).  
+__But don't you dare to use this crappy Microsoft built in editor!__
+
+Practically it's very supportive of course,
+to use a IDE that has good markdown support in terms of code-highlighting,
+table formatting, etc.  
+Below are collected tips for different IDE's.
+
+=== "VSCode"
+    recommended extensions:  
+    _these are the extension id's searchable from vscode_
+
+    - `editorconfig.editorconfig`
+    - `waderyan.gitblame`
+    - `yzhang.markdown-all-in-one`
+    - `jebbs.plantuml`
+
+[gitscm-win]: https://git-scm.com/download/win
+[java-net]: https://jdk.java.net/
+[maven-dl]: https://maven.apache.org/download.cgi
+[python-win-dl]: https://www.python.org/downloads/windows/

mkdocs.yml

@@ -28,7 +28,7 @@ nav:
           - Ticket: 'api/systems/gitlab/ticket.md'
           - Ticketsystem: 'api/systems/gitlab/ticket-system.md'
   - Developers Guide:
-    - Index: 'developers-guide/index.md'
+    - Machine Setup: 'developers-guide/machine-setup.md'
     - Styleguide: 'developers-guide/styleguide.md'
     - Workflow: 'developers-guide/workflow.md'