Commit 298d4767 authored by Florent Chehab's avatar Florent Chehab

feat(documentation): reogarnized and added doc about notifictions in the frontend.

* Reorganized documentation folder
* Rorganized documentation sidebar in browser
* Added documentation about notifications in the frontend #74
* Tweaks

Bonus: more readable docker-compose
parent 62328a0d
# Main docker-compose file for the project to coordinate all the docker related stuff.
# To build from local image, use the `build: ...` attibute and not the `image` attribute.
# Main ports summary:
# - 8000: main app
# - 5000: documentation
version: '3.7'
services:
# Service for the backend app.
backend:
# Get the image from the registry
......@@ -34,6 +40,7 @@ services:
depends_on:
# Required that the `database` service is up and running.
- database
# Service for the postgres database
database:
# Use of classic image
......@@ -46,6 +53,7 @@ services:
volumes:
# Add a volume to store the DB data.
- postgres_data:/var/lib/postgresql/data/
# Service to handle frontend live developpments and building
frontend:
# Build image from Dockerfile
......@@ -60,6 +68,8 @@ services:
- 3000:3000
# replicate the view stats port
- "8888:8888"
# Service to provide a local documentation
documentation:
build: ./documentation
volumes:
......@@ -69,7 +79,9 @@ services:
ports:
# replicate the server port
- "5000:5000"
gen_doc_uml: # service to generate the UML of the backend
# service to generate the UML of the backend
gen_doc_uml:
image: floawfloaw/plantuml
volumes:
- .:/usr/src/app
......
......@@ -4,11 +4,11 @@ Architecture
Visualization of the `backend` app architecture.
Vue complète :
![Architecture](generated/architecture.svg)
![Architecture](../../generated/architecture.svg)
Vue plus précise :
![other_core](generated/abstract.svg)
![other_core](generated/core.svg)
![AbstractModules](generated/university.svg)
![Architecture](generated/location.svg)
![Architecture](generated/user.svg)
![other_core](../../generated/abstract.svg)
![other_core](../../generated/core.svg)
![AbstractModules](../../generated/university.svg)
![Architecture](../../generated/location.svg)
![Architecture](../../generated/user.svg)
Tests
Backend tests
======
*Rex-DRI* comes in with several *tests* that you can perform locally using the commands `make test_backend` and `make test_frontend` once the project is up and running (`make up`).
## Backend testing
### General words
## General words
Testing the backend is handled with a combination of `pytest` and `Django` (and `pytest-django` package).
......@@ -17,20 +14,10 @@ Also, there are tests regarding some custom validation.
Finally, the initial and example loading data scripts are tested.
### Documentation
## Documentation
Some usefull links to get inspired:
- [General information about testing in Django](https://docs.djangoproject.com/fr/2.1/topics/testing/overview/)
- [`pytest` documentation](https://docs.pytest.org/en/latest/)
- [`pytest-django` documentation](https://pytest-django.readthedocs.io/en/latest/)
## Frontend testing
### General words
Testing the frontend is done with `jest`.
### Documentation
- [`jest` documentation](https://jestjs.io/docs/en/getting-started)
Notifications in the app
======
The visual notifications in the app are based on the [`Snackbars`](https://material-ui.com/demos/snackbars/) component of our frontend framework `material-ui`.
To ease the use of notifications throughout the app, we use the [`notistack`](https://github.com/iamhosseindhv/notistack) module.
## Don't miss notistack doc
The very good documentation is available [here](https://iamhosseindhv.com/notistack).
## How to use it
### 1. The standard way\*
!> \* Only when it's used in a *class-based* component that won't be extended.
You simply need to wrap your component in the `withSnackbar` function provided by `notistack` when exporting it.
```js
import React, { Component } from "react";
import { withSnackbar } from "notistack";
/**
* Never forget to comment your code by the way
*
* @class ADumbComponent
* @extends {Component}
*/
class ADumbComponent extends Component {
// ....
}
export default withSnackbar(ADumbComponent);
```
By doing so, two `props` functions will be added to your component: `enqueueSnackbar` (to dispatch a notification) and `closeSnackbar` (to close a specific notification, see [doc](https://iamhosseindhv.com/notistack)).
Then in your component you can simply call `enqueueSnackbar`:
```js
this.props.enqueueSnackbar(
"My awesome message",
{
variant: "success", // or "error", "warning" or "info"
autoHideDuration: 5000 // duration of the notification
// And other parameters you can find in the doc.
}
)
```
### 2. The \* workaround
When the condition for 1 is not met, you can use the `Notifier` component available in `frontend/src/components/common/Notifier.js`. This component will display a notification as soon as it is added to the DOM. You should pass the parameters in its `props`, as follow:
```jsx
<Notifier
message={"My awesome error message."}
options={{ variant: "error" }}
/>
```
Frontend tests
======
*Rex-DRI* comes in with several *tests* that you can perform locally using the commands `make test_backend` and `make test_frontend` once the project is up and running (`make up`).
## General words
Testing the frontend is done with `jest`.
## Documentation
- [`jest` documentation](https://jestjs.io/docs/en/getting-started)
......@@ -9,7 +9,7 @@ You can load everything in one command by connecting to the `Django` shell:
make django_shell
```
And running:
And by running:
```python
from backend_app.load_data import load_all
......
Set-up
=======
## Git
*If you don't have `git` install on your computer, look online and install it :tongue: .*
Then, you can simply clone the project repository:
```bash
git clone git@gitlab.utc.fr:rex-dri/rex-dri.git && cd rex-dri
```
## Docker and docker-compose
This projects takes advantage of `docker` and `docker-compose` to ease the setup process, continuous integration, deployments, etc.
!> If you don't have those tools on your computer, you first need to install them. You can do so by following those guides:
- [`docker`](https://docs.docker.com/install/)
- [`docker-compose`](https://docs.docker.com/compose/install/)
*To run `Docker` your user needs to belong to the `docker` user-group (creating during the install process) or to `sudo` all `docker`-related commands. The last solution is a bit annoying when developing, so you can add your user to the `docker` group: `sudo usermod -aG docker your-user`. You can find "who" is your user with the command `whoami`. **The change will take effect after you restart your computer (or close your session and reopen it)**.*
Once this is done, don't forget that you need to have docker running before using `docker-compose`. For example, on `Fedora 29` you need to run the following command:
```bash
sudo service docker start
```
Finally you can start-up all `docker` related *stuff* using the command:
```bash
make up--build
```
**When you launch the project for the first time you'll most likely have the backend container crash due to the lack of some static files. Make sure not to stop the launch process until you see `frontend_1 | ℹ 「wdm」: Compiled successfully` in the console. Then you can stop the command (`CTRL+C`) and do `make up`; you shouldn't have issues thereafter.**
You can look at the `Makefile` to have more information on that last command and the other ones that are available.
To start all the `docker` images you will then only need to use the `make up` command.
**Important: the `make up` command actually lunches `docker-compose` in an *attached* mode, so that you can easily access the logs of the docker containers. If you quit it (e.g. with `CTRL+C`), this will stop all the docker containers. So usually, you should lunch it in one shell, don't touch that shell and use another one for all other `make` command related to the containers that were lunched.**
## Initialization
To initialize the database associated with the project, you need to connect to the `backend` image:
*(As explained in the **important** section, this has to be done in another shell than the one you used for the `make up` command.)*
```bash
make shell_backend
```
Then:
- Migrate the `Django` models:
```bash
./manage.py migrate
```
- Create the initial revisions:
```bash
./manage.py createinitialrevisions
```
_NB: this last command should be run every time you migrate (modify/add) some models._
When this is done you can exit the `docker` image shell (`CTRL + D`).
## Checking setup
### Backend
Run the commands bellow to check that the backend is setup correctly:
*(Simple check of the setup)*.
```bash
make check_backend
```
*(Run `Python` tests)*
```bash
make test_backend
```
### Frontend
Run the commands bellow to check that the frontend is setup correctly:
*(Build the `React` app)*
```bash
make build_frontend
```
*NB: At the time of the writing of the documentation there is no test for the frontend...*
## You are done
Once the `Docker` images are up (command `make up`), the app is available on [http://localhost:8000](http://localhost:8000).
**Don't miss the other pages of the documentation, in particular [the one about loading 'init' data in the app](./init_data).**
Contributors
=========
?> Thank you to all of those who contributed to this project :thumbsup:
- Solène Aboud
- Ségolène Brisemeur
- Florent Chehab
- Alexandre Lanceart
*Find all the people who contributed [here](https://gitlab.utc.fr/rex-dri/rex-dri/graphs/master).*
About this documentation
========
## `docsify.js`
## docsify.js
This markdown based documentation is made available in a nice way using [`docsify`](https://docsify.js.org/).
......
Use of `Docker`
==============
## General comment
As said in the introduction, this project makes use of `docker` and `docker-compose`. Their are several `Dockerfile` spraid across the project that creates the required `docker` image.
Then the `docker-compose.yml` file coordinates everything: environment variables, ports, volumes, etc.
You can have a look at those files for more comments.
## Use in Gitlab
The `backend` image is also stored on [https://gitlab.utc.fr/rex-dri/rex-dri/container_registry](https://gitlab.utc.fr/rex-dri/rex-dri/container_registry) to be easily used in `Gitlab CI`.
As it seemed not possible to do the same for the `frontend` image due to the fact that the `node_modules` folder couldn't be kept during `CI`, the image is basically regenerated in `CI`.
When ran locally, the `npm i` command (installing the `Node` dependencies) is run everytime with `make up` to make sure your `node_modules` folder is up to date.
## Updating the image on Gitlab
If you are not connected to the registry yet, do it:
```bash
docker login registry.gitlab.utc.fr
```
To update the images stored on the Gitlab repository, run for instance:
```bash
docker build ./backend --compress --tag registry.gitlab.utc.fr/rex-dri/rex-dri/backend:latest
```
And push it:
```bash
docker push registry.gitlab.utc.fr/rex-dri/rex-dri/backend:latest
```
## Updating the images from Gitlab
To do so, run `make docker-pull`.
## Issues with `__pycache__`
If you have issues at some point with `__pycache__` files, you can delete them:
```bash
find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | sudo xargs rm -rf
```
## Issues with Django migrations
With the docker setup, Django migrations are created from within the container and as a result those files are own by the docker user.
If you have issues with git regarding the migrations files (i.e. they don't disappear when you change branch), you need to become an owner of the files: `chown -R $(id -u):$(id -g) backend`.
<!-- docs/_sidebar.md -->
* [Introduction](/)
* [Set-up](set-up.md)
* [Use of `Docker`](docker.md)
* [Initializing data](init_data.md)
* [Architecture](architecture.md)
* [Tags](tags.md)
* [API](API.md)
* [Tests](tests.md)
* [About this documentation](this_doc.md)
* [Contributions](contributions.md)
- Getting started
* [Introduction](GettingStarted/introduction.md)
* [Set-up](GettingStarted/set-up.md)
* [Initializing data](GettingStarted/init_data.md)
- Application documentation
- Backend
* [Architecture](Application/Backend/architecture.md)
* [Tags](Application/Backend/tags.md)
* [API](Application/Backend/API.md)
* [Tests](Application/Backend/tests.md)
- Frontend
* [Tests](Application/Frontend/tests.md)
* [Notifications](Application/Frontend/notifications.md)
- Comments about technologies used
* [Use of `Docker`](Technologies/docker.md)
- Other
* [About this documentation](Other/this_doc.md)
* [Contributions](Other/contributions.md)
Contributors :thumbsup:
=========
- Florent Chehab
Use of `Docker`
Use of Docker
==============
## General comment
......
......@@ -21,8 +21,12 @@
search: {
placeholder: 'Search for...',
noData: 'No result :(',
paths: ['/installation']
// paths: ['/Application', '/GettingStarted', "Technologies", "/Other"]
},
alias: {
"/": "/GettingStarted/introduction.md",
"/.*/_sidebar.md": "/_sidebar.md",
}
}
</script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
......@@ -30,6 +34,9 @@
<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
<script src="https://unpkg.com/docsify-copy-code@2"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-python.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-javascript.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-jsx.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-sql.min.js"></script>
</body>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment