doc: Create a doc for the different Python start subsystems.

README.md

@@ -106,15 +106,21 @@ If you need help, maybe our [troubleshooting guide](/doc/troubleshooting.md) hel
 Quickstart
 ----------
 
-* How do I get this to run on my box?
-    * See [doc/building.md](/doc/building.md).
-
-* I compiled everything. Now how do I run it?
+* **How do I get this to run on my box?**
+    1. [Fork](https://help.github.com/articles/fork-a-repo/) the repo.
+    1. Install dependencies. See [doc/building.md](/doc/building.md#dependency-installation) to get instructions for your favorite platform.
+    1. Build the project:
+   ```
+   ./configure --download-nyan
+   make
+   ```
+
+* **I compiled everything. Now how do I run it?**
     * Execute `./bin/run`.
     * [The convert script](/doc/media_convert.md) will transform original assets into openage formats, which are a lot saner and more moddable.
     * Use your brain and react to the things you'll see.
 
-* Waaaaaah! It
+* **Waaaaaah! It...**
     * segfaults
     * prints error messages I don't want to read
     * ate my dog

doc/code/testing.md

@@ -15,9 +15,9 @@ Tests run without user interaction to check for errors automatically.
 All tests are run automatically by [Kevin](https://github.com/SFTtech/kevin/) for pullrequests.
 
 
-You can invoke them with `./run test -a` or `make test`
+You can invoke them with `bin/run test -a` or `make test`
 
-Have a look at `./run test --help` for further options.
+Have a look at `bin/run test --help` for further options.
 
 
 You are encouraged to write tests for all your contributions, as well as other components that currently lack testing.
@@ -35,7 +35,7 @@ They usually produce lots of output on stdout or may even be interactive. Python
 
 All tests must be registered in `openage/testing/testlist.py` (else the game won't know about them).
 
-Also see `./run test --help`.
+Also see `bin/run test --help`.
 
 ## Adding new tests
 
@@ -135,7 +135,7 @@ C++ demos don't support `argv`; if you want that, make it a Python demo in a `.p
 
 Similar to Python tests, but have one argument, `argv`. Pass arguments in the invocation:
 
-    ./run test -d prime_demo 100
+    bin/run test -d prime_demo 100
 
 Example demo:
 

doc/running.md

@@ -0,0 +1,121 @@
+# How to run openage?
+
+This document explains the different run modes in openage.
+
+1. [Quickstart](#quickstart)
+2. [Modes](#modes)
+   1. [`game`](#game)
+   2. [`main`](#main)
+   3. [`test`](#test)
+   4. [`convert`](#convert)
+   5. [`convert-file`](#convert-file)
+   6. [`convert-export-api`](#convert-export-api)
+   7. [`codegen`](#codegen)
+
+
+## Quickstart
+
+After building the project with the commands
+
+```
+./configure
+make
+```
+
+you can execute
+
+```
+bin/run
+```
+
+from the same subfolder. This automatically selects the [`game` mode](#game) as default
+to start a new game instance and also creates all necessary configs.
+
+If prompts appear, follow the instructions and choose what you think is best. It's
+almost idiot-proof!
+
+
+## Modes
+
+Modes can be selected manually by appending the `bin/run` prompt with the mode name.
+
+### `game`
+
+```
+bin/run game
+```
+
+Start the engine and immediately create a new game instance. This run mode is supposed
+to jump straight into a game (or replay recording).
+
+If no converted modpacks can be found, this mode will start with a prompt asking if
+the user wants to convert any before initializing the game.
+
+It's the default run mode.
+
+
+### `main`
+
+```
+bin/run main
+```
+
+This run mode is supposed to start a main menu or launcher which allows configuring a
+game. Neither of these are implemented at the moment, so `main` just does the same
+thing as `game`.
+
+
+### `test`
+
+```
+bin/run test
+```
+
+Used for running [tests and engine demos](code/testing.md). These show off selected
+subsystems of the engine.
+
+
+### `convert`
+
+```
+bin/run convert
+```
+
+Runs the [asset conversion](media_convert.md) subsystem which creates openage modpacks
+from original game installations.
+
+
+### `convert-file`
+
+```
+bin/run convert-file
+```
+
+Allows converting single media files using the original game formats to open formats
+(PNG for graphics, OPUS for sounds).
+
+
+### `convert-export-api`
+
+```
+bin/run convert-export-api
+```
+
+Exports the [openage modding API](nyan/README.md) nyan objects to a modpack that can
+be loaded by the engine.
+
+This is supposed to be temporary solution until the modding API is finalized. Currently,
+the modding API nyan objects are hardcoded into the converter. In the future, the
+modding API modpack should be part of the engine config which is loaded by both the engine
+the converter subsystem as a single source of truth.
+
+
+### `codegen`
+
+```
+bin/run codegen
+```
+
+Runs the code generation logic for the build process. In particular, this generates code
+for [mako](https://www.makotemplates.org/) templates and creates the test lists for the
+[testing](code/testing.md) subsystem.