From 62eea677d83b079836f422e5929edc466a4ec177 Mon Sep 17 00:00:00 2001
From: Josef Olsson <josol381@student.liu.se>
Date: Thu, 20 May 2021 22:03:58 +0000
Subject: [PATCH] Resolve "Documentation"
---
.vscode/tasks.json | 10 ++--
README.md | 12 ++--
client/README.md | 4 +-
docs/source/contact.md | 23 +++----
docs/source/development.rst | 4 +-
docs/source/development/client.md | 6 +-
docs/source/development/external.md | 4 +-
docs/source/development/further.md | 35 +++++++++--
docs/source/development/server.md | 4 +-
docs/source/development/vscode.md | 36 ++++++-----
docs/source/documentation/client.md | 2 +
docs/source/documentation/general.md | 2 +-
docs/source/documentation/server.md | 2 +-
docs/source/installation.rst | 2 +-
docs/source/installation/client.md | 6 +-
docs/source/installation/server.md | 6 +-
docs/source/introduction.md | 26 --------
docs/source/introduction.rst | 10 ++++
docs/source/introduction/project.md | 32 ++++++++++
docs/source/introduction/system.md | 35 +++++++++++
docs/source/overview.rst | 4 +-
docs/source/overview/client.md | 36 +++++++++++
docs/source/overview/overview.md | 16 ++---
docs/source/overview/server.md | 80 +++++++++++++++----------
docs/source/testing.rst | 2 +-
docs/source/testing/client.md | 2 +
docs/source/testing/e2e.md | 2 +
docs/source/testing/server.md | 4 +-
docs/source/user_manual/admin.md | 12 ++--
docs/source/user_manual/editor.md | 24 ++++----
docs/source/user_manual/login.md | 4 +-
docs/source/user_manual/presentation.md | 28 +++++----
server/README.md | 4 +-
33 files changed, 322 insertions(+), 157 deletions(-)
delete mode 100644 docs/source/introduction.md
create mode 100644 docs/source/introduction.rst
create mode 100644 docs/source/introduction/project.md
create mode 100644 docs/source/introduction/system.md
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
index 45f88f11..5582399b 100644
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -82,21 +82,21 @@
}
},
{
- "label": "Generate server documentation",
+ "label": "Generate documentation",
"type": "shell",
- "command": "../env/Scripts/activate; ./make html",
+ "command": "../server/env/Scripts/activate; ./make html",
"problemMatcher": [],
"options": {
- "cwd": "${workspaceFolder}/server/docs"
+ "cwd": "${workspaceFolder}/docs"
}
},
{
- "label": "Open server documentation",
+ "label": "Open documentation",
"type": "shell",
"command": "start index.html",
"problemMatcher": [],
"options": {
- "cwd": "${workspaceFolder}/server/docs/build/html"
+ "cwd": "${workspaceFolder}/docs/build/html"
}
},
{
diff --git a/README.md b/README.md
index 10a4debc..e0a31a75 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ To install the client and server needed to run the application, look in their re
## Using
After installing both the client and the server, you are ready to run the application.
-This is done in VSCode by pressing `ctrl+shift+b` and running the `Start client and server` task.
+This is done in VS Code by pressing `ctrl+shift+b` and running the `Start client and server` task.
The terminals for the client and server will now be seen on the right and left, respectively.
After making a change to either the client or the server while they are running, simply reload the page to see the changes immediately.
@@ -27,7 +27,7 @@ To begin working, you need to choose an issue and create a branch from it.
4. Choose one of these issues and click on it.
5. Add yourself as an asignee (in top right corner).
6. Press the little green downarrow on the right of the `Create merge request` button and select and press `Create branch`.
-7. Open the project in VSCode.
+7. Open the project in VS Code.
8. Type `git pull`. This will fetch the new branch you just created.
9. Switch to it by running `git checkout <branch>`. (Example: `git checkout 5-add-login-api`)
@@ -49,7 +49,7 @@ This is done in two steps:
First you need to prepare your branch to be merged and then create a merge request.
First, prepare your branch to be merged.
-1. Open the project in VSCode.
+1. Open the project in VS Code.
2. Checkout your branch, if you are not already on it (`git checkout <branch>`).
3. Run `git pull origin dev`. This will try to merge the latest changes from `dev` into your branch. This can have a few different results:
- There will be no changes, which is fine.
@@ -70,12 +70,12 @@ You cannot approve your own merge requests but once it's approved anyone can mer
### Merge conflicts
You will need to manually merge if there is a merge conflict between your branch and another.
-This is simply done by opening the project in VSCode and going to the Git tab on the left (git symbol).
+This is simply done by opening the project in VS Code and going to the Git tab on the left (git symbol).
You will then see som files marked with `C`, which indicates that there are conflicts in these files.
You will have to go through all of the merge conflicts and solve them in each file.
-A merge typically looks like the code snippet at the bottom of this document in plain text (try opening this in VSCode and see how it looks).
+A merge typically looks like the code snippet at the bottom of this document in plain text (try opening this in VS Code and see how it looks).
The only thing you really need to do is removing the `<<<<<<<`, `=======` and `>>>>>>>` symbols from the document, although you don't have to do it by hand.
-In VSCode, you can simply choose if you want to keep incoming changes (from the branch you merging into), current changes (from your branch) or both.
+In VS Code, you can simply choose if you want to keep incoming changes (from the branch you merging into), current changes (from your branch) or both.
Solve all the merge conflicts in every file and run the tests to make sure it still works.
Commit and push your changes when you are done.
diff --git a/client/README.md b/client/README.md
index 23cb2057..81cfbb93 100644
--- a/client/README.md
+++ b/client/README.md
@@ -6,10 +6,10 @@ This documents describes how to install and run the client.
You will need to do the following things to install the client:
-1. Install [Visual Studio Code](https://code.visualstudio.com/) (VSCode).
+1. Install [Visual Studio Code](https://code.visualstudio.com/) (VS Code).
2. Install [Node (LTS)](https://nodejs.org/en/).
3. Clone this repository if you haven't done so already.
-4. Open the project folder in VSCode.
+4. Open the project folder in VS Code.
5. Open the integrated terminal by pressing `ctrl+ö`.
6. Type the following commands (or simply paste them) into your terminal:
diff --git a/docs/source/contact.md b/docs/source/contact.md
index 53155d8c..eebe583d 100644
--- a/docs/source/contact.md
+++ b/docs/source/contact.md
@@ -1,16 +1,17 @@
# Contact
The people involved in the project, their email, their role in the project, what they worked on generally and, if anything, they worked on most will be described below.
-The head developer on each general area will also be given.
Please feel free to contact us if you have any questions.
-| Name | Email | Role | General | Special |
-| ------------------ | ----------------------- | ---------------------- | -------- | ------------------- |
-| Albin Henriksson | albhe428@student.liu.se | Testledare | Frontend | Huvudutvecklare |
-| Sebastian Karlsson | sebka991@student.liu.se | Arkitekt | Frontend | |
-| Victor Löfgren | viclo211@student.liu.se | Konfigurationsansvarig | Backend | Dokumentation |
-| Björn Modée | bjomo323@student.liu.se | Kvalitetsamordnare | Frontend | Redux |
-| Josef Olsson | josol381@student.liu.se | Teamledare | Backend | |
-| Max Rüdiger | maxru105@student.liu.se | Dokumentansvarig | Frontend | |
-| Carl Schönfelder | carsc272@student.liu.se | Utvecklingsledare | Backend | Huvudutvecklare |
-| Emil Wahlqvist | emiwa210@student.liu.se | Analysansvarig | Frontend | Presentationseditor |
+| Namn | Email | Roll | Generellt | Speciellt |
+| ------------------ | ----------------------- | ---------------------- | --------- | ---------------------- |
+| Albin Henriksson | albhe428@student.liu.se | Testledare | Frontend | |
+| Sebastian Karlsson | sebka991@student.liu.se | Arkitekt | Frontend | |
+| Victor Löfgren | viclo211@student.liu.se | Konfigurationsansvarig | Backend | Dokumentation, Sockets |
+| Björn Modée | bjomo323@student.liu.se | Kvalitetsamordnare | Frontend | Redux |
+| Josef Olsson | josol381@student.liu.se | Teamledare | Backend | |
+| Max Rüdiger | maxru105@student.liu.se | Dokumentansvarig | Frontend | |
+| Carl Schönfelder | carsc272@student.liu.se | Utvecklingsledare | Backend | Databas |
+| Emil Wahlqvist | emiwa210@student.liu.se | Analysansvarig | Frontend | Presentationseditor |
+
+[comment]: # (Should this really be in swedish?)
\ No newline at end of file
diff --git a/docs/source/development.rst b/docs/source/development.rst
index 6dc13f16..89085b0c 100644
--- a/docs/source/development.rst
+++ b/docs/source/development.rst
@@ -1,8 +1,8 @@
Development
===========
-In this section we give all the instructions necessary to continue the development of this project.
-We also give some recommentations for how to go about it.
+This section will give all the instructions necessary to continue the development of this project.
+Some recommendations for how to go about it will also be given.
.. toctree::
:maxdepth: 2
diff --git a/docs/source/development/client.md b/docs/source/development/client.md
index 5ae08c70..c868be74 100644
--- a/docs/source/development/client.md
+++ b/docs/source/development/client.md
@@ -1,7 +1,11 @@
# Frontend
+[comment]: # (TODO)
+
## Working with TypeScript
+[comment]: # (TODO)
+
### npm
`npm` is the node package manager.
@@ -14,4 +18,4 @@ To uninstall a module, run `npm uninstall <module>`.
To install all project dependencies, run `npm install`.
-Remember to install the project dependencies whenever someone else has added new ones to the project.
+It is important to remember to install the project dependencies whenever someone else has added new ones to the project.
diff --git a/docs/source/development/external.md b/docs/source/development/external.md
index 84e4a756..ee8c3b35 100644
--- a/docs/source/development/external.md
+++ b/docs/source/development/external.md
@@ -1,6 +1,6 @@
# External programs
-We also used some other programs help the development.
+These are some useful programs that can help with the development.
## Postman
@@ -12,3 +12,5 @@ It's very helpful when developing APIs.
[DB Browser for SQlite](https://sqlitebrowser.org/) is used to see what is currently stored in the database.
You can even edit values.
+
+[comment]: # (Add VS CODE?)
\ No newline at end of file
diff --git a/docs/source/development/further.md b/docs/source/development/further.md
index 6daad4e6..543de426 100644
--- a/docs/source/development/further.md
+++ b/docs/source/development/further.md
@@ -1,11 +1,34 @@
# Further development
Because the project was time limited a lot is left to be done.
-A few ideas for things to be improved are given here.
+Below we will give two different types of things to improve.
+The first type is functionality, bugs and aesthetics which improves the usability of the system.
+The second type is refactoring which is basically just things related to the source code.
+This won't effect the end user but will certainly improve the system as a whole.
-## Replacing reqparse
+## Functionality, bugs and aesthetics
-As mentioned in [Parsing request](../overview/server.html#parsing-request), the reqparse module from RestX is deprecated and should be replaced with for example marshmallow.
-Parsing is a rather small and simple matter which makes it quite fine not to use the most optimal tool, but it should nevertheless be replaced.
-This would also make it possible to generate better documentation by providing both the expected paramters and return value from an API.
-This was looked into and deemed not trivial with the current solution.
+Most of the basic functionality of the system is already completed.
+There are however a few major things left to be done.
+
+### Different question types
+
+The system needs to support a lot of different types of questions.
+A list of all the questions that needs to be supported (and more) can be found on [Teknikattan scoring system](https://github.com/TechnoX/teknikattan-scoring-system/blob/master/kandidatarbete_teknikattan.md).
+
+## Refactoring
+
+Here we will give a list of things we think will improve the system.
+It is not certain that they are a better solutions but definitely something to look into.
+
+### Replace Flask-RESTX with flask-smorest
+
+[comment]: # (This is already implemented)
+
+We currently use [Flask-RESTX](https://flask-restx.readthedocs.io/en/latest/) to define our endpoints and parse the arguments they take, either as a query string or in the body.
+But when responding we use [Marshmallow](https://flask-smorest.readthedocs.io/en/latest/) to generate the JSON objects to return.
+We believe that [flask-smorest](https://flask-smorest.readthedocs.io/en/latest/) would integrate a lot better with Marshmallow.
+This would give us the ability to more easily show the expected arguments and the return values for our endpoints using Swagger (when visiting `localhost:5000`).
+Currently we only show the route.
+The work required also seems to be rather small because they look quite similar.
+This would also remove the deprecated [reqparse](https://flask-restx.readthedocs.io/en/latest/parsing.html) part from Flask-RESTX, which is desirable.
diff --git a/docs/source/development/server.md b/docs/source/development/server.md
index 16d36a1e..ef234d03 100644
--- a/docs/source/development/server.md
+++ b/docs/source/development/server.md
@@ -13,7 +13,7 @@ When [installing the server](../installation/server.md) you installed `virtualen
Python uses `pip` to manage it's packages.
Here we briefly describe to use it.
-All of the following instructions assume you have created and activated a virtual environment.
+All of the following instructions assume you have created and activated a virtual environment and are located in the server folder.
To install a package, run `pip install <package>`.
@@ -23,4 +23,4 @@ To save a package as a dependency to the project, run `pip freeze > requirements
To install all project dependencies, run `pip install -r requirements.txt`.
-Remember to install the project dependencies whenever someone else has added new ones to the project.
+Remember to install the project dependencies whenever you or someone else has added new ones to the project.
diff --git a/docs/source/development/vscode.md b/docs/source/development/vscode.md
index 97e30af2..86c4a97f 100644
--- a/docs/source/development/vscode.md
+++ b/docs/source/development/vscode.md
@@ -1,26 +1,28 @@
# Visual Studio Code
-The development of this project was mainly done using Visual Studio Code (VSCode).
+The development of this project was mainly done using Visual Studio Code (VS Code).
It is not that surprising, then, that we recommend you use it.
## Extensions
-When you first open the repository in Visual Studio Code it will ask you to install all recommended extesions, which you should do.
+When you first open the repository in Visual Studio Code it will ask you to install all recommended extensions, which you should do.
We used a few extensions to help with the development of this project.
-The Python and Pylance extensions help with linting Python code, auto imports, syntax highliting and much more.
+The Python and Pylance extensions help with linting Python code, auto imports, syntax highlighting and much more.
-Prettier is an extension used to format JavsScript and TypeScript.
-ESLint is used to lint JavsScript and TypeScript code.
+Prettier is an extension used to format JavaScript and TypeScript.
+ESLint is used to lint JavaScript and TypeScript code.
-Live Share is an extension thats used to code together at the same time, much like a Google Docs document.
-But there was a few issues with the Python extension that made Live Share hard to work with.
+[comment]: # ("is used to lint JavaScript" what is lint? It's not explained)
+
+Live Share is an extension that is used to write code together at the same time, much like a Google Docs document.
+There were however a few issues with the Python extension that made Live Share hard to work with.
## Tasks
-A task in VSCode is a simple action that can be run by pressing `ctrl+shift+p`, searching for and selecting `Tasks: Run Task`.
-These tasks a configured in the `.vscode/tasks.json` file.
-Tasks that are build tasks can also be run with `ctrl+shift+b`.
+A task in VS Code is a simple action that can be run by pressing `ctrl+shift+p`, searching for and selecting `Tasks: Run Task`.
+These tasks are configured in the `.vscode/tasks.json` file.
+Tasks that are marked as build tasks (starting and testing tasks as well as populate) can also be run with `ctrl+shift+b`.
A few such tasks has been setup in this project and will be described below.
The `Start server` task will start the server.
@@ -31,14 +33,16 @@ The `Start client and server` task will start both the client and the server.
The `Populate database` task will populate the database with a few competitions, teams, users and such. Look in the `populate.py` to see exactly what it adds. Remember to always run this after changing the structure of the database.
-The `Test server` task will run the server tests located in the `tests/` folder.
+The `Test server` task will run the server tests located in the `server/tests/` folder.
+
+The `Open server coverage` task can only be run after running the server tests (`Test server` task) and will open the coverage report generated by those tests in a web browser.
-The `Open server coverage` can only be run after running the server tests and will open the coverage report generated by those tests in a webbrowser.
+The `Unit tests` task will run the unit tests for the client.
-The `Test client` task will run `npm test`.
+The `Run e2e tests` task will run the end-to-end tests.
-The `Open client coverage` can only be run after running the client tests and will open the coverage report generated by those tests in a webbrowser.
+The `Open client coverage` task can only be run after running the client tests (`Unit tests` task) and will open the coverage report generated by those tests in a web browser.
-The `Generate documentation` will generate the project documentation, i.e. this document, in the `docs/build/html/` folder.
+The `Generate documentation` task will generate the project documentation, i.e. this document, in the `docs/build/html/` folder.
-The `Open documentation` can only be run after generating the documentation and will open it in a webbrowser.
+The `Open documentation` task can only be run after generating the documentation and will open it in a web browser.
diff --git a/docs/source/documentation/client.md b/docs/source/documentation/client.md
index ca1dcfe8..fe424fe5 100644
--- a/docs/source/documentation/client.md
+++ b/docs/source/documentation/client.md
@@ -16,3 +16,5 @@ start ./docs/index.html
```
If you want to include the documentation from the tests, go to the file `client/tsconfig.json` and comment out the line `"exlude": "**/*.test.*"`.
+
+[comment]: # (There should be a task for this, or does one exist already?)
\ No newline at end of file
diff --git a/docs/source/documentation/general.md b/docs/source/documentation/general.md
index 8787da1e..d75f2cc4 100644
--- a/docs/source/documentation/general.md
+++ b/docs/source/documentation/general.md
@@ -17,5 +17,5 @@ choco install make
You also need to [install the server](../installation/server.md).
You should now be able to generate the documentation by activating the Python virtual environment, navigating to `docs/` and running `make html`.
-Alternatively you can also run the [VSCode task](../development/vscode.html#tasks) `Generate server documentation`, which will do the same thing.
+Alternatively you can also run the [VS Code task](../development/vscode.html#tasks) `Generate documentation`, which will do the same thing.
If everything went well you should be able to open it by running (from the `docs/` folder) `start ./build/html/index.html` or running the task `Open documentation`, which does the same thing.
diff --git a/docs/source/documentation/server.md b/docs/source/documentation/server.md
index 9bbff58f..e3c9a7e2 100644
--- a/docs/source/documentation/server.md
+++ b/docs/source/documentation/server.md
@@ -16,7 +16,7 @@ sphinx-quickstart
You will be asked a few questions about how to configure Sphinx.
Just press enter on all, which will use the default.
-You can enter the correct projet name and/or author if you want, but it's not necessary, no one but you will see it anyway.
+You can enter the correct project name and/or author if you want, but it's not necessary, no one but you will see it anyway.
Then will need to modify a few files.
First add the following code snippet after the first block of comments, above the "project information" comment, in the file `./server/docs/conf.py`:
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 30ba35ea..7152a72c 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -1,7 +1,7 @@
Installation
============
-Here we will describe how to install the application.
+This section will describe how to install the application.
You will need to install both the client and the server.
.. toctree::
diff --git a/docs/source/installation/client.md b/docs/source/installation/client.md
index 7548e08a..e5768e9c 100644
--- a/docs/source/installation/client.md
+++ b/docs/source/installation/client.md
@@ -5,7 +5,7 @@ In order to install the client, you will need to do the following:
Install [Node (LTS)](https://nodejs.org/en/).
-Clone [teknikattan-scoring-system](https://gitlab.liu.se/tddd96-grupp11/teknikattan-scoring-system).
+Clone the git repository [teknikattan-scoring-system](https://gitlab.liu.se/tddd96-grupp11/teknikattan-scoring-system).
Open a terminal and navigate to the root of the cloned project.
@@ -18,4 +18,6 @@ npm install
You should now be ready to start the client.
Try it by running `npm run start`.
-A webpage should open where you can see the [login page](../user_manual/login.md).
+A web page should open where you can see the [login page](../user_manual/login.md).
+
+[comment]: # (Should we mention the task for starting the client?)
diff --git a/docs/source/installation/server.md b/docs/source/installation/server.md
index 137cbfb6..3c867f43 100644
--- a/docs/source/installation/server.md
+++ b/docs/source/installation/server.md
@@ -5,7 +5,7 @@ In order to install the server, you will need to do the following:
Install [Python](https://www.python.org/downloads/).
-Clone [teknikattan-scoring-system](https://gitlab.liu.se/tddd96-grupp11/teknikattan-scoring-system).
+Clone the git repository [teknikattan-scoring-system](https://gitlab.liu.se/tddd96-grupp11/teknikattan-scoring-system).
Open a terminal and navigate to the root of the cloned project.
@@ -32,7 +32,7 @@ On Linux/Mac:
source env/bin/activate
```
-Install all project dependencies:
+Lastly, install all project dependencies:
```bash
pip install -r requirements.txt
@@ -41,3 +41,5 @@ pip install -r requirements.txt
You should now be ready to start the server.
Try it by running `python main.py` and navigate to `localhost:5000`.
If everything worked as it should you should see a list of all available API calls.
+
+[comment]: # (Should we mention the task for starting the server?)
diff --git a/docs/source/introduction.md b/docs/source/introduction.md
deleted file mode 100644
index 26f22429..00000000
--- a/docs/source/introduction.md
+++ /dev/null
@@ -1,26 +0,0 @@
-# Introduction
-
-This system was allows a user to create, edit and host competitions.
-
-## Login
-
-After logging in you will be able to see all competitions and edit them.
-If you're an admin you will also be able to see all users and edit them.
-You are also able to connect to an active competition from the same screen you used to login.
-
-## Editor
-
-The editor allows you to edit competitions.
-You can add, remove and reorder slides.
-You can add, delete and edit teams, text and image components, question type, correcting instructions and background image.
-
-## Active competitions
-
-You can also start a competition.
-This will let other people join it with codes that can be seen either before or after starting a presentation.
-Then when you switch slides, start the timer or show the current score it will also happen for every other person connected to the same competition.
-
-Depending on which code someone uses to join an active competition they will see different things, which we call different views.
-The team view will allow the user to answer the questions.
-The judge view will allow the user to see correct answers and give a score to the questions answered by a team.
-The audience view will show the current slide.
diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
new file mode 100644
index 00000000..4af75475
--- /dev/null
+++ b/docs/source/introduction.rst
@@ -0,0 +1,10 @@
+Introduction
+============
+
+This is a short introduction to both the project as a whole and our system.
+
+.. toctree::
+ :maxdepth: 2
+
+ introduction/project
+ introduction/system
diff --git a/docs/source/introduction/project.md b/docs/source/introduction/project.md
new file mode 100644
index 00000000..efe0cee6
--- /dev/null
+++ b/docs/source/introduction/project.md
@@ -0,0 +1,32 @@
+# Introduction to the project
+
+This is a short introduction to the project.
+There are several links to other relevant things to read before choosing this project.
+
+## Before choosing this project
+
+There are a lot of things this system needs to do.
+To get a complete description, see the [original repository](https://github.com/TechnoX/teknikattan-scoring-system#beskrivning-av-hur-man-anv%C3%A4nder-systemet) from Teknikåttan.
+There you will see exactly what is expected of the system (click on each picture to see a video that will give a more in-depth explanation).
+You may also what to look at the [description of the project](https://github.com/TechnoX/teknikattan-scoring-system/blob/master/kandidatarbete_teknikattan.md), if you have not already done so.
+There is a lot to read (and watch) on these two links, but in doing so you will get a complete picture of the requirements.
+Make sure you understand what this project entails before continuing with it, it is not as "simple" as it might first seem.
+
+## Our perspective
+
+This was a fun project.
+In contrast to some other previous projects the purpose of this one, what it's requirements are and why it's useful, is clear.
+It is really fun developing a product you know (if it turns out well) many people will appreciate, use, and see.
+
+But on the other hand the project is large.
+There was a group that worked on this project before us.
+We could have continued their project when we began, but we decided not to.
+This was in part due to it not really working and in part due to lack of documentation.
+We hope to have learned from that mistake.
+That is why we have made proper documentation (the one you are reading right now!) and a decent, working foundation of the system.
+We have also made an effort to document the code as much as possible.
+We hope you continue on our efforts if you choose this project.
+
+## Contact us
+
+If you have any questions about the project, our system or anything, feel free to [contact](../contact.md) any of us.
diff --git a/docs/source/introduction/system.md b/docs/source/introduction/system.md
new file mode 100644
index 00000000..5163562b
--- /dev/null
+++ b/docs/source/introduction/system.md
@@ -0,0 +1,35 @@
+# Introduction to our system
+
+This system allows a user to create, edit and host competitions.
+Below it is in short described what the system allows you to do.
+If you want a more exact description (with pictures!), see the [user manual](../user_manual.rst)
+
+## Login
+
+After logging in you will be able to see all competitions and edit them.
+If you're an admin you will also be able to see all users and edit them.
+You will also be able to connect to an active competition from the same screen you used to login.
+
+## Editor
+
+The editor allows you to edit competitions.
+You can add, remove and reorder slides.
+You can add, delete and edit:
+
+- teams
+- text and image components
+- questions
+- question types
+- correcting instructions
+- background image.
+
+## Active competitions
+
+You can also start a competition.
+This will let other people join it with codes that can be seen either before or after starting a presentation.
+Then when you switch slides, start the timer or show the current score, it will also happen for every other person connected to the same competition.
+
+Depending on which code someone uses to join an active competition they will see different things, which we call different _views_.
+The _team view_ will allow the user to answer the questions.
+The _judge view_ will allow the user to see correct answers and give a score to the questions answered by a team.
+The _audience view_ will show the current slide.
diff --git a/docs/source/overview.rst b/docs/source/overview.rst
index 1314ce28..fe607291 100644
--- a/docs/source/overview.rst
+++ b/docs/source/overview.rst
@@ -1,8 +1,8 @@
System overview
===============
-Here we briefly describe how the entire system works.
-Then we go into more detail about the client and the server.
+This is a brief overview of how the entire system works.
+There is then more detail about the client and the server.
.. toctree::
:maxdepth: 2
diff --git a/docs/source/overview/client.md b/docs/source/overview/client.md
index 51c0cd88..0187b5e9 100644
--- a/docs/source/overview/client.md
+++ b/docs/source/overview/client.md
@@ -1 +1,37 @@
# Client overview
+
+The client is the main part of the system.
+It is divided into 4 pages: login, admin, presentation editor and active competitions (presentations).
+The presentations is also further divided into four different views: operator view, audience view, team view and judge view.
+
+## Competitions and Presentations
+
+In this project competitions are often refered to when meaning un-active competitions while presentations are refered to when meaning active competitions involving multiple users and sockets connecting them.
+
+## File structure
+
+All of the source code for the pages in the system is stored in the `client/src/pages/` folder.
+For each of the different parts there is a corresponding file that ends in Page, for example `JudgeViewPage.tsx` or `LoginPage.tsx`.
+This is the main file for that page.
+All of these pages also has their own and shared components, in the folder relative to the page `./components/`.
+Every React component should also have their responding test file.
+
+## Routes
+
+All pages have their own route which is handled in `client/src/Main.tsx`. Futhermore the admin page has one route for each of the tabs which helps when reloading the site to select the previously selected tab. There is also a route for logging in with code which makes it possible to go to for example `localhost:3000/CODE123` to automatically join a competition with that code.
+
+## Authentication
+
+Authentication is managed by using JWT from the API. The JWT for logging in is stored in local storage under `token`. The JWT for active presentations are stored in local storage `RoleToken` so for example the token for Operator is stored in local storage under `OperatorToken`.
+
+## Prettier and Eslint
+
+[Eslint](https://eslint.org/) is used to set rules for syntax, [prettier](https://prettier.io/) is then used to enforce these rules when saving a file. Eslint is set to only warn about linting warnings. These libraries have their own config files which can be used to change their behavior: `client/.eslintrc` and `client/.prettierrc`
+
+## Redux
+
+[Redux](https://eslint.org/) is used for state management along with the [thunk](https://github.com/reduxjs/redux-thunk) middleware which helps with asynchronous actions. Action creators are under `client/src/actions.ts`, these dispatch actions to the reducers under `client/src/reducers.ts` that update the state. The interfaces for the states is saved in each reducer along with their initial state. When updating the state in the reducers the action payload is casted to the correct type to make the store correctly typed.
+
+## Interfaces
+
+In `client/src/interfaces` all interfaces that are shared in the client is located. `client/src/interfaces/ApiModels.ts` and `client/src/interfaces/ApiRichModels.ts` includes all models from the api and should always be updated when editing models on the back-end. This folder also includes some more specific interfaces that are re-used in the client.
diff --git a/docs/source/overview/overview.md b/docs/source/overview/overview.md
index dd1eccce..5a46ed19 100644
--- a/docs/source/overview/overview.md
+++ b/docs/source/overview/overview.md
@@ -5,19 +5,21 @@ The terms frontend and client as well as backend and server will be used interch
-First we have the main server which is written in Python using the micro-framework Flask.
-Then have a fairly small Node server who's only function is to serve the React frontend pages.
-Lastly we have the frontend which is written in TypeScript using React and Redux.
+First there is the main server which is written in Python using the micro-framework Flask.
+Then there is a fairly small Node server with only one function, to serve the React frontend pages.
+Lastly there is the frontend which is written in TypeScript using React and Redux.
## Communication
-The frontend communicates with the backend in two ways.
-All of the following ways are authorized on the server to make sure that who ever tried to communicate has the correct access level.
+The frontend communicates with the backend in two ways, both of which are authorized on the server.
+This is to make sure that whoever tries to communicate has the correct level of access.
### API
-API calls are used for simple functions the client wants to perform, such as getting, editing and saving data.
-These are sent from the client to the backend Node server who will proxy the request to the main Python server.
+[comment]: # (What does "that will proxy the request to the main Python server" mean?)
+
+API calls are used for simple functions that the client wants to perform, such as getting, editing, and saving data.
+These are sent from the client to the backend Node server that will proxy the request to the main Python server.
The request will then be handled there and the response will be sent back.
The Node server will then send them back to the client.
diff --git a/docs/source/overview/server.md b/docs/source/overview/server.md
index 314ff853..9f322c4e 100644
--- a/docs/source/overview/server.md
+++ b/docs/source/overview/server.md
@@ -1,75 +1,93 @@
# Server overview
-The server has two main responsibilites.
+The server has two main responsibilities.
The first is to handle API calls from the client to store, update and delete information, such as competitions or users.
It also needs to make sure that only authorized people can access these.
-The other is to sync slides, timer and answers between clients in an active competition.
+The other responsibility is to sync slides, timer and answers between clients in an active competition.
Both of these will be described in more detail below.
## Receiving API calls
-An API call is a way the client can communicates with the server.
+An API call is a way for the client to communicate with the server.
When a request is received the server begins by authorizing it (making sure the person sending the request is allowed to access the route).
-After that it makes sure that it got all information in the request it needed.
-The server will then do the thing the client requested.
-And finally it will need to generate repsonse, usually in the form of an object from the database.
+After that it confirms that it got all information in the request that it needed.
+The server will then process the client request.
+Finally it generates a response, usually in the form of an object from the database.
All of these steps are described in more detail below.
### Routes
-Each route which is possible to call is specified in the files in the `app/apis/` folder.
+Each existing route that can be called is specified in the files in the `app/apis/` folder.
All available routes can also be seen by navigating to `localhost:5000` after starting the server.
### Authorization
-When the server receives an API call the first thing it does is to authorize it.
+When the server receives an API call it will first check that the call is authorized.
The authorization is done using JSON Web Tokens (JWT) by comparing the contents of them with what is expected.
-Whenever a client logs into an account or joins a competition, it is given a JWT generated by the server, and the client will need to use this token in every subsequent request sent to the server to authenticate itself.
+Whenever a client logs into an account or joins a competition, it is given a JWT generated by the server, and the client will need to use this token in every subsequent request sent to the server in order to authenticate itself.
-What authorization to be done on the server is specified by the `@protect_route()` decorator.
-This decorator specifies who is allowed to access this route, which can either be users with specific roles, or people who have joined competitions with specific views.
-If the route is not decorated everyone is allowed to access it, the only routes currently like that is logging in as a user and joining a competition, by necessity.
+The needed authorization is specified by the `@protect_route()` decorator.
+This decorator specifies who is allowed to access this route, which can either be users with specific roles, or people that have joined competitions with specific views.
+If the route is not decorated everyone is allowed to access it, and the only routes currently like that is, by necessity, logging in as a user and joining a competition.
+
+#### JSON Web Tokens (JWT)
+
+JSON Web Tokens (JWT) are used for authentication, both for API and socket events.
+A JWT is created on the server when a user logs in or connects to a competition.
+Some information is stored in the JWT, which can be seen in the file `server/app/apis/auth.py`.
+The JWT is also encrypted using the secret key defined in `server/configmodule.py`.
+(NOTE: Change this key before running the server in production).
+The client can read the contents of the JWT but cannot modify them because it doesn't have access to the secret key.
+This is why the server can simply read the contents of the JWT to be sure that the client is who it says it is.
### Parsing request
-After the request is authorized the server will need to parse contents of the request.
+After the request is authorized the server will need to parse the contents of the request.
The parsing is done with [reqparse](https://flask-restx.readthedocs.io/en/latest/parsing.html) from RestX (this module is deprecated and should be replaced).
-Each API call expects different parameters in different places and this is specificied in each of the files in `app/apis/` folder, together with the route.
+Each API call expects different parameters in different places and this is specified in each of the files in `app/apis/` folder, together with the route.
### Handling request
-After the request has been authorized and parsed the server needs to act on the request.
-What the server does of course depends on the route and given arguments, but it usually gets, edits or deletes something from the database.
+After the request has been authorized and parsed the server will process the request.
+What it does depends on the route and the given arguments, but it usually gets, edits or deletes something from the database.
The server uses an SQL database and interfaces to it via SQLAlchemy.
Everything related to the database is located in the `app/database/` folder.
### Responding
-When the server is done handling the request it usually responds with an item from the database.
+When the server har processed the request it usually responds with an item from the database.
Converting a database object to json is done with [Marsmallow](https://marshmallow.readthedocs.io/en/stable/).
-How to do this conversion is specified in two files in in the folder `app/core/`.
-The file `schemas.py` just converts a record in the database field by field.
+This conversion is specified in two files in the folder `app/core/`.
+The file `schemas.py` converts a record in the database field by field.
The file `rich_schemas.py` on the other hand converts an `id` in one table to an entire object in the another table, thus the name rich.
-In this way, for example, an entire competition with it's teams, codes, slides and the slides' questions and components can be returned in a single API call.
+In this way, for example, an entire competition with its teams, codes, slides and the slides' questions and components can be returned in a single API call.
## Active competitions
-Slides, timers and answers needs to be synced during an active presentation.
+Slides, timers, and answers needs to be synced during an active presentation.
This is done using SocketIO together with flask_socketio.
-Events sent is also authorized via json web tokens.
-Whenever client joins a competition they will connect via sockets.
-Only a single instance of a competition can be active at a time.
+Sent events are also authorized via JWT, basically the same way as the for the API calls.
+But for socket events, the decorator that is used to authenticate them is `@authorize_user()`.
+Whenever a client joins a competition they will connect via sockets.
+A single competition cannot be active more than once at the same time.
+This means that you will need to make a copy of a competition if you want to run the same competition at several locations at the same time.
All of the functionality related to an active competition and sockets can be found in the file `app/core/sockets.py`.
+The terms *active competition* and *presentation* are equivalent.
### Starting and joing presentations
-Whenever a client types in a code in the client, the code will be checked via the `api/auth/login/code` API call.
-If there is such a code and it was an operator code, the client will receive a JWT it will need to use to authenticate itself for there on out.
-It will also emit the `start_presentation` event to start the presentation.
-If there is such a code and the associated competition is active, the client will also receive a JWT, regardless if it was an operator code or not.
-In this case the client will instead emit the `join_presentation` event.
+Whenever a code is typed in to the client it will be checked via the `api/auth/login/code` API call.
+If there is such a code and it was an operator code, the client will receive the JWT it will need to use to authenticate itself.
+If there is such a code and the associated competition is active, the client will also receive a JWT for its corresponding role.
+Both of these cases will be handled by the default `connect` event, using the JWT received from the API call.
+The server can see what is stored in the JWT and do different things depending on its contents.
### Syncing between clients
-The operator will emit `set_slide` and `set_timer` events that syncs their slides and timers between all clients connected to the same presentation.
-The operator can also emit `end_presentation` to end the current presentation, which will disconnect all connected clients.
+[comment]: # (What does `sync` mean? It isn't explained)
+
+The operator will emit the `sync` event and provide either a slide or a timer to update it on the server.
+The server will then send `sync` to all connected clients with the updated values, regardless of what was actually updated.
+The server will also store the timer and active slide in order to `sync` clients when they join.
+The operator can also emit `end_presentation` to disconnect all clients from its competitions.
+This will also end the presentation.
diff --git a/docs/source/testing.rst b/docs/source/testing.rst
index 3ef832a7..d154d226 100644
--- a/docs/source/testing.rst
+++ b/docs/source/testing.rst
@@ -3,7 +3,7 @@ Testing
Here we briefly describe how we have tested the system.
Both unit tests for the client and server has been made.
-Some end to end tests has also been made that tests both the server and client at the same time.
+Some end-to-end tests have also been made that tests both the server and client at the same time.
.. toctree::
:maxdepth: 2
diff --git a/docs/source/testing/client.md b/docs/source/testing/client.md
index ad39ab88..b0201a48 100644
--- a/docs/source/testing/client.md
+++ b/docs/source/testing/client.md
@@ -1 +1,3 @@
# Testing the client
+
+[comment]: # (TODO)
\ No newline at end of file
diff --git a/docs/source/testing/e2e.md b/docs/source/testing/e2e.md
index 25670eae..62d70386 100644
--- a/docs/source/testing/e2e.md
+++ b/docs/source/testing/e2e.md
@@ -1 +1,3 @@
# End to end tests
+
+[comment]: # (TODO)
\ No newline at end of file
diff --git a/docs/source/testing/server.md b/docs/source/testing/server.md
index 538918df..e113982b 100644
--- a/docs/source/testing/server.md
+++ b/docs/source/testing/server.md
@@ -3,10 +3,10 @@
The Python testing framework used to test the server is [pytest](https://docs.pytest.org/).
The server tests are located in the folder `./server/tests`.
-The tests are further divided into files that test the database `test_db.py` and test the api `test_api.py`.
+The tests are further divided into files that test the database (`test_db.py`) and test the api (`test_api.py`).
The file `test_helpers.py` is used to store some common functionality between the tests, such as adding default values to the database.
There are also some functions that makes using the api easier, such as the `get`, `post` and `delete` functions.
-Run the tests by running the [VSCode task](../development/vscode.html#tasks) `Test server`.
+Run the tests by running the [VS Code task](../development/vscode.html#tasks) `Test server`.
After that you can see what has been tested by opening the server coverage using the task `Open server coverage`.
diff --git a/docs/source/user_manual/admin.md b/docs/source/user_manual/admin.md
index 19f87d82..10ee20fd 100644
--- a/docs/source/user_manual/admin.md
+++ b/docs/source/user_manual/admin.md
@@ -10,7 +10,7 @@ In the bottom left you will be able to logout by pressing the "Logga ut" button.
## Regions
The regions tab will show all regions.
-You will be able to create a new region by entering its name at the top and click the "+" button.
+To create a new region, enter its name at the top and then click the "+" button.
@@ -18,23 +18,23 @@ You will be able to create a new region by entering its name at the top and clic
The users tab will allow you to see all users, their name, region and role.
You will also be able to create new users by clicking the "Ny användare" button.
-By click the three dots "..." you will be able to edit or delete that user.
-You will also be able to search for and filter users by region or role.
+By clicking the three dots "..." you will be able to edit or delete that user.
+You will also be able to search for and filter users by their region or role.
## Competitions
The competitions tab will allow you to see all competitions, their name, region and year.
-You will also be able to create new competitions by click the "Ny tävling" button and edit exisiting ones by clicking on their name.
+You will also be able to create a new competition by clicking the "Ny tävling" button or edit existing ones by clicking on their name.
By click on the three dots "..." you will be able to start, show the codes for, copy or delete that competition.
### Competition codes
-After pressing the three dots "..." for a competition and pressing "Visa koder", all the codes for that competition will be shown.
+By pressing the three dots "..." for a competition and then pressing "Visa koder", all the codes for that competition will be shown.
Here you will see what view each code is associated with and what the code is.
-You will also be able to generate a new code, copy the code or copy a link to the code that will let other people join, or even host, a competition directly.
+You will also be able to generate a new code, copy the code or copy a link to the code that will let others join, or even host, a competition directly.
diff --git a/docs/source/user_manual/editor.md b/docs/source/user_manual/editor.md
index 7a9fd8a1..7091cce6 100644
--- a/docs/source/user_manual/editor.md
+++ b/docs/source/user_manual/editor.md
@@ -1,31 +1,35 @@
# Editor
+[comment]: # 'Explain where to find the competition name. Perhaps an image or link to Admin?'
+
After clicking on a competition name you will enter the editor and will be able to edit it.
-The Teknikåttan logo in the top left corner will take you back to the Admin page.
-To the left you will see all slides, a newly created competition will have one empty default slide.
+The Teknikåttan logo in the top left corner will take you back to the Admin page and right under that all slides are shown.
+A newly created competition will have one empty default slide.
Switch to a different slide by clicking on it.
-In the bottom left corner you will be able to add a new slide.
+In the bottom left corner you will be able to add a new slide using the "Ny sida" button.
Delete or copy a slide simply by right clicking on it and choosing the appropriate option.
-In the top right corner you will be able to change which view you are see and edit.
+In the top right corner you will be able to change which view you see and edit.
+
+
## Competition settings
To the right you will see the active tab "Tävling", which will show and let you edit everything about the entire competition.
There you will be able to edit the competition name, add a new team and a background image.
-The background image for the competition will be used for all slids in the competition.
-
-
+The background image for the competition will be used for all slides in the competition.
## Slide settings
If you choose the "Sida" tab, you will be able to edit the current slide.
In the top right you can change the question type of the current slide.
For all question types you will be able to add a timer for how long the teams have to answer that question.
-Depending on which type you choose you will have different options below.
+Depending on which type you choose, you will have different options below.
For this example we will choose multiple choice ("Kryssfråga").
-For this question type you will have the option to add a title to the question and how much score a correct answer on the question will give.
+For this question type you will have the option to add a title to the question and how much many points a correct answer yields.
For this question type you will also be able to add alternatives, which the teams will be able to choose between during a competition.
Below that you will be able to add and remove text and image components as well as a background image.
-The background image for the competition can be overridden by explicitly setting one on a specific page.
+The background image for the competition can be overridden by explicitly setting it on a specific page.
+
+[comment]: # 'Perhaps mention right clicking a component to make a copy to another view?'
diff --git a/docs/source/user_manual/login.md b/docs/source/user_manual/login.md
index b019bae9..ec0424b2 100644
--- a/docs/source/user_manual/login.md
+++ b/docs/source/user_manual/login.md
@@ -4,7 +4,7 @@ The login page will let you either login as a user or join a competition with a
## User
-The first page you will be presented with when acessing the site is the login page.
+The first page you will be presented with when accessing the site is the login page.
From here you can login with your account by typing your email and password in their respective fields and pressing the "Logga in" button.
@@ -15,3 +15,5 @@ You can also choose the "Tävling" tab.
Here you can enter your six character long code and by pressing the "Anslut till tävling" button you will be able to join a competition.
+
+These codes can be accessed from [Admin](admin.md).
diff --git a/docs/source/user_manual/presentation.md b/docs/source/user_manual/presentation.md
index e8f8b6e1..2bb125a5 100644
--- a/docs/source/user_manual/presentation.md
+++ b/docs/source/user_manual/presentation.md
@@ -1,26 +1,32 @@
+[comment]: # "Why is this file named 'presentation' but the main headline is 'Active competitions'?"
+
# Active competitions
There are many different views during a competition.
-Below we describe how to start a competition, how to join a competition and how the different kinds of views work.
+Below it is described how to start a competition, how to join a competition, and how the different kinds of views work.
+
+## Competition codes
+
+You can join a competition with codes.
+This can either be done by pasting the link that can be copied when listing the codes or can be typed by hand in the login page.
+All the views have different purposes and therefore looks a little bit different from one another.
## Operator
-There is two ways to start a competition.
+There are two ways to start a competition.
The first way is to navigate to the competition manager, press the three dots "..." and press "Starta".
You will then enter the operator view.
-From here you will be able to go bewteen slides with the "<" and ">" buttons or start the timer, both will be synced between all clients connected to that competition.
+From there you will be able to go between slides with the "<" and ">" buttons or start the timer, both will be synced between all clients connected to that competition.
You will also be able to view the scores for the teams and view all codes to the competition.
## Team
-You can also join the competition with codes.
-This can either be done by pasting the link that can be copied when listing the codes or can be typed by hand on the login page.
-All the views have a different purpose and therefore looks a little bit different.
+[comment]: # 'What is meant with "(or the code for one of the teams)"? Doesnt a team have to log in using a code?'
The team view (or the code for one of the teams) will be used by teams.
-It shows the current slide and allows the user to answer questions on the slide that will be saved.
+It shows the current slide (that the operator has decided) and allows the user to answer questions on the slide that will be saved.
@@ -32,9 +38,11 @@ The audience view will look like the operator view but without the buttons.
## Judge
+[comment]: # 'Update image to show that the current slide is highlighted.'
+
The judge view will show show the same slide as team view.
-To the left you will be able to move between different slides without affecting the other clients.
-To the right you will see what the teams have answered on every question, how much score each team got on each question, how much they have in total and be able to set the score of a team on the current question.
-In the bottom right you will see instructions for how to correct the current question.
+To the left you will be able to move between different slides without affecting the other clients and will be shown och which slide the operator currently is.
+To the right you will see what the teams have answered on every question, what score each team got on each question, their total score and be able to set the score of a team on any and all questions.
+In the bottom right you will see instructions for how to grade the current question.
diff --git a/server/README.md b/server/README.md
index 84d994d8..f03f6021 100644
--- a/server/README.md
+++ b/server/README.md
@@ -6,10 +6,10 @@ This document describes how to install and run the server.
You will need to do the following things to install the server:
-1. Install [Visual Studio Code](https://code.visualstudio.com/) (VSCode).
+1. Install [Visual Studio Code](https://code.visualstudio.com/) (VS Code).
2. Install [Python](https://www.python.org/downloads/).
3. Clone this repository if you haven't done so already.
-4. Open the project folder in VSCode.
+4. Open the project folder in VS Code.
5. Open the integrated terminal by pressing `ctrl+ö`.
6. Type the following commands into your terminal:
--
GitLab