Resolve "Documentation"

.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"
       }
     },
     {

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.
 

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:
 

docs/source/contact.md

 # 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

docs/source/development.rst

 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

docs/source/development/client.md

 # 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.

docs/source/development/external.md

 # 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

docs/source/development/further.md

 # 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.

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.

docs/source/development/vscode.md

 # 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.

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

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.

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`:

docs/source/installation.rst

 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::

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?)

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?)

docs/source/introduction.rst

+Introduction
+============
+
+This is a short introduction to both the project as a whole and our system.
+
+.. toctree::
+    :maxdepth: 2
+
+    introduction/project
+    introduction/system

docs/source/introduction/project.md

+# 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.

docs/source/introduction.md → docs/source/introduction/system.md

-# Introduction
+# Introduction to our system
 
-This system was allows a user to create, edit and host competitions.
+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 are also able to connect to an active competition from the same screen you used to login.
+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, question type, correcting instructions and background image.
+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.
+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.
+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.

docs/source/overview.rst

 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