Merge branch 'documentation' into 'master'

Add documentation

See merge request !20

JS-README.md

+# Which JavaScript files does Portal need to run?
+
+The important JavaScript files can be found in `/portal/static/js/`!
+This is mostly Mithril.js.
+
+## `/portal/static/js/components`
+
+[TODO] furtherly explain the components
+
+This is where the frontend components are located. The components are divided into two categories: `pages` and `pieces`. **Mithril.js** uses `pages` to render the main content of the website, while `pieces` are used to render smaller components that are used in multiple places. `pieces` then are embedded into `pages`.
+
+This could help you around
++ [Mithril.js documentation](https://mithril.js.org/)
++ [Convert plain HTML to Mithril](https://arthurclemens.github.io/mithril-template-converter/index.html)
+
+
+
+### `/portal/static/js/components/pages`
+
+
+
+Generally, everything having its own tab in the Navbar is a `page`. They are the first components that are rendered when the website is loaded.
+
++ `Base.mjs`
++ `Fachschaftssitzung.mjs`
++ `FsServices.mjs`
++ `Login.mjs`
++ `M.mjs`
++ `Start.mjs`
++ `UniServices.mjs`
++ `Unlock.mjs`
+
+### `/portal/static/js/components/pieces`
+
+These are the smaller components that are embedded in multiple places.
+
+
++ `AccountRequired.mjs`
++ `Agenda.mjs`
++ `BoxedButton.mjs`
++ `ButtonAndTextLink.mjs`
++ `Nav.mjs`
++ `NavPageLink.mjs`
++ `PasswordinVault.mjs`
++ `ServiceLink.mjs`
++ `Toast.mjs`
++ `UnlockRequired`
+
+## `/portal/static/js/model`
+
+### `/portal/static/js/model/Service.mjs`
+
+This renders an individual service.
+
+### `/portal/static/js/model/Services.mjs`
+
+This renders the list of our services.
+
+## `/portal/static/js/account.mjs`
+
+Here, after the login, a session token is created and stored in the `LocalStorage`.
+It also responsible for ensuring the validity and non-expiry of the session token.
+Users get logged in and logged out here.
+
+## `/portal/static/js/gitlab.mjs`
+
+Arcane magic. We get our Fachschaftssitzung protocols here.
+Also, there's some yapping about the Same Origin Policy, might be interesting, but misses a TL;DR.
+
+## `/portal/static/js/portal.mjs`
+
+This is the main file that initializes the Mithril.js app and sets up the routing.
+

README.md

@@ -2,8 +2,81 @@
 
 # Development
 
+## Setup
+
+### with docker
+
 To run a flask shell inside the container:
 
 ```sh
 sudo docker exec -it portal-app-1 flask shell
 ```
+
+### without docker
+
+```bash
+# mkdir yourself into the portal directory
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+export FLASK_APP=portal
+alembic upgrade head # to create (and update!) the database
+flask run
+```
+
+---
+#### Wichtig:
+
+Alembic must always be up to date in order to update the database schema.
+Please run `alembic upgrade head` after pulling changes from the repository.
+---
+
+## How to move around in this repo
+
+## `/portal/`: Main Application
+
+Here are all the important tech-stack related stuff and some Python files for Flask, contained in a cozy space
+
+### `/portal/api/`: API Endpoints (Python)
+
+Here you can find the API endpoints, written in Python
+
+### `/portal/model`: database models (Python)
+
+We use `SQLAlchemy` to interact with the database. The models are defined in this folder.
+
+### `/portal/static`: CSS, JS, images, API documentation
+
+This is giving the frontend some love and, more importantly, its purpose and functionality. The API documentation is also laying around here.
+
+#### `/portal/static/css` (CSS, obviously)
+
+Here you can find the CSS files for the frontend. The main CSS file is `main.css`.
+
+#### `/portal/static/docs`
+
+Here you can find the documentation for the API in its respective versions.
+API specifications (`openapi-spec.yaml`) are written in OpenAPI 3.0.0 and are located in the `/api/{version}` folder.
+
+
+#### `/portal/static/img`: Frag nicht, was für Bilder. Einfach Bilder. I won't translate this.
+
+What did you expect?
+
+#### `/portal/static/js`: JavaScript files
+
+Lol, that should actually ![have its own README](JS-README.md).
+
+It contains all the JavaScript files that are responsible for the frontend interactions.
+
+
+### `/portal/templates`
+
+These are the HTML files that Flask renders. They are written in Jinja2, which is a template engine for Python.
+
+### `.py`-files
+
++ `__init__.py`: Fortunately, explaining this was not a Prog2 exam question
++ `db_config.py`: [TODO] Have fun, Jakob. Database configuration (arcane magic).
++ `main.py`: The Flask server is in here
++ `problem_details.py`: RFC 7807-compliant problem details responses for the API.