Docs: Add more info about debugging (logging and FSM)

7 files changed, 50 insertions, 3 deletions

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 58509f8..0fea28b 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -4,7 +4,9 @@
 - [Getting Started](./gettingstarted/README.md)
   - [Building](./gettingstarted/building.md)
   - [Testing](./gettingstarted/testing.md)
-  - [Debugging](./gettingstarted/debugging.md)
+  - [Debugging](./gettingstarted/debugging/README.md)
+	- [Logging](./gettingstarted/debugging/logging.md)
+	- [Finite State Machine](./gettingstarted/debugging/fsm.md)
 - [API](./api/README.md)
   - [Go](./api/go/README.md)
 	- [Functions](./api/go/functions.md)
diff --git a/docs/src/gettingstarted/README.md b/docs/src/gettingstarted/README.md
index 152d491..7c7912d 100644
--- a/docs/src/gettingstarted/README.md
+++ b/docs/src/gettingstarted/README.md
@@ -1,2 +1,4 @@
 # Getting Started
-This chapter contains the steps to get started with the Go library. You will learn how to build the library, what the structure of the library is and how to test the code.
+This chapter contains the steps to get started with the Go library. You will learn how to build the library, how to run the test suite and how to debug possible errors.
+
+The documentation on how to use this library will be given in the next chapter: [API](../api/index.html).
diff --git a/docs/src/gettingstarted/debugging.md b/docs/src/gettingstarted/debugging.md
deleted file mode 100644
index 1e584c9..0000000
--- a/docs/src/gettingstarted/debugging.md
+++ /dev/null
@@ -1 +0,0 @@
-# Debugging
diff --git a/docs/src/gettingstarted/debugging/README.md b/docs/src/gettingstarted/debugging/README.md
new file mode 100644
index 0000000..e3a1ecd
--- /dev/null
+++ b/docs/src/gettingstarted/debugging/README.md
@@ -0,0 +1,6 @@
+# Debugging
+
+To debug this library, e.g. to discover bugs or to see how it works internally, the library comes with a few nice additions.
+
+## The debug variable
+To enable debugging, set debugging to True in the method that registers the code with the library (see [API](../api/index.html)). This sets the logging level to `INFO` (meaning show all messages), and generates a Finite State Machine (FSM) PNG file. We explain in more detail what these two components (logging and FSM) exactly are and how they can be used.
diff --git a/docs/src/gettingstarted/debugging/fsm.md b/docs/src/gettingstarted/debugging/fsm.md
new file mode 100644
index 0000000..891b0ea
--- /dev/null
+++ b/docs/src/gettingstarted/debugging/fsm.md
@@ -0,0 +1,30 @@
+# Finite State Machine
+
+The eduvpn-common library uses a Finite State Machine internally to keep track of which state the client is in and to communicate data callbacks(e.g. to communicate the Authorization URL in the OAuth process to the client).
+
+## Viewing the FSM
+To view the FSM in an image, set the debug variable to `True`. This outputs the graph with a `.graph` extension in the client-specified config directory (See [API](../../api/index.html)). The format of this graph is from [Mermaid](https://mermaid-js.github.io/mermaid/#/).
+
+If you have the [Mermaid command line client](https://github.com/mermaid-js/mermaid-cli) installed, the Go library will automatically provide a PNG file in the same directory of the `.graph` file. We recommend to use an image viewer that has auto-reload capabilities, such as [feh](https://feh.finalrewind.org/)[^1] for Linux.
+
+## FSM Example
+The following is an example of the FSM when the client has obtained a Wireguard/OpenVPN configuration from an eduVPN server
+
+![](./fsm_example.png)
+
+The current state is highlighted in the <span style="color:cyan">cyan</span> color.
+
+## State explanation
+The states mean the following:
+
+- `DEREGISTERED`: The client has not registered with the library yet, the state variables are not initialized
+- `NO_SERVER`: The client is registered, but has not chosen a server yet
+- `CHOSEN_SERVER`: The client has chosen a server to connect to
+- `OAuth_Started`: The OAuth process has been started. This means that the client needs to redirect to the browser so that the user can login and approve the application
+- `Authenticated`: The OAuth process has finished. The client now has tokens and is thus authenticated
+- `Request_Config`: The client is in the process of requesting an OpenVPN/Wireguard configuration from the server
+- `Ask_Profile`: The server has multiple profiles for which a config can be obtained, the client must show an UI of the profiles. The user then selects one of these profiles to exit this state
+- `Has_Config`: The client now has a configuration that it can use to connect using OpenVPN/Wireguard
+- `Connected`: The client is connected to the VPN
+
+[^1]: We recommend the following arguments for feh: `feh --auto-reload --keep-zoom-vp directory/example.png`. This auto reloads the feh image viewer and keeps the zoom level when reloading
diff --git a/docs/src/gettingstarted/debugging/fsm_example.png b/docs/src/gettingstarted/debugging/fsm_example.png
new file mode 100644
index 0000000..c495124
--- /dev/null
+++ b/docs/src/gettingstarted/debugging/fsm_example.png
diff --git a/docs/src/gettingstarted/debugging/logging.md b/docs/src/gettingstarted/debugging/logging.md
new file mode 100644
index 0000000..a1cfc97
--- /dev/null
+++ b/docs/src/gettingstarted/debugging/logging.md
@@ -0,0 +1,8 @@
+# Logging
+As said, logging is used. The logging gets saved in a client-specified directory (see [API](../../api/index.html)). Logging has the following levels:
+
+- `INFO`: Messages purely for info, these do not indicate any errors. They are merely there for debugging purposes
+- `WARNING`: This message indicates a warning, this can be e.g. non-fatal errors
+- `ERROR`: Fatal errors which refuses the app from working
+
+By default only messages below or equal to `WARNING` are logged (`WARNING`, `ERROR`). However, if the debug variable is set to `True`, all messages will be logged into the log file.