README.md 4.13 KB
Newer Older
Skia's avatar
Skia committed
1 2
[![pipeline status](https://ae-dev.utbm.fr/ae/Sith/badges/master/pipeline.svg)](https://ae-dev.utbm.fr/ae/Sith/commits/master)
[![coverage report](https://ae-dev.utbm.fr/ae/Sith/badges/master/coverage.svg)](https://ae-dev.utbm.fr/ae/Sith/commits/master)
Sli's avatar
Sli committed
3
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
Sli's avatar
Sli committed
4
[![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://ae-dev.zulipchat.com)
Skia's avatar
Skia committed
5

Skia's avatar
Skia committed
6
## Sith AE
Skia's avatar
Skia committed
7

Skia's avatar
Skia committed
8
### Get started
Skia's avatar
Skia committed
9 10 11

To start working on the project, just run the following commands:

12 13 14 15 16 17 18 19
```bash
git clone https://ae-dev.utbm.fr/ae/Sith.git
cd Sith
virtualenv --system-site-packages --python=python3 env
source env/bin/activate
pip install -r requirements.txt
./manage.py setup
```
Skia's avatar
Skia committed
20

Skia's avatar
Skia committed
21
To start the simple development server, just run `python3 manage.py runserver`
Skia's avatar
Skia committed
22

Sli's avatar
Sli committed
23 24 25 26
### Logging errors with sentry

To connect the app to sentry.io, you must set the variable SENTRY_DSN in your settings custom. It's composed of the full link given on your sentry project

Skia's avatar
Skia committed
27
### Generating documentation
Skia's avatar
Skia committed
28

Skia's avatar
Skia committed
29 30
There is a Doxyfile at the root of the project, meaning that if you have Doxygen, you can run `doxygen Doxyfile` to
generate a complete HTML documentation that will be available in the *./doc/html/* folder.
Skia's avatar
Skia committed
31

Skia's avatar
Skia committed
32
### Dependencies:
33
See requirements.txt
Skia's avatar
Skia committed
34

Skia's avatar
Skia committed
35
You may need to install some dev libraries like `libmysqlclient-dev`, `libssl-dev`, `libjpeg-dev`, `python3-xapian`, or `zlib1g-dev` to install all the
Skia's avatar
Skia committed
36 37 38 39 40
requiered dependancies with pip. You may also need `mysql-client`. Don't also forget `python3-dev` if you don't have it
already.

You can check all of them with:

41
```bash
Skia's avatar
Skia committed
42
sudo apt install libmysqlclient-dev libssl-dev libjpeg-dev zlib1g-dev python3-dev libffi-dev python3-dev libgraphviz-dev pkg-config python3-xapian
Skia's avatar
Skia committed
43
```
Skia's avatar
Skia committed
44

45 46 47 48 49 50 51 52
On macos, you will need homebrew

```bash
brew install --build-from-source xapian --with-python
```

If it doesn't work it's because it need [this pull request](https://github.com/Homebrew/homebrew-core/pull/34835) to be validated.

Skia's avatar
Skia committed
53 54
The development is done with sqlite, but it is advised to set a more robust DBMS for production (Postgresql for example)

Sli's avatar
Sli committed
55 56
### Collecting statics for production:

Sli's avatar
Sli committed
57 58
We use scss in the project. In development environment (DEBUG=True), scss is compiled every time the file is needed. For production, it assumes you have already compiled every files and to do so, you need to use the following commands : 

59
```bash
Sli's avatar
Sli committed
60 61
./manage.py collectstatic # To collect statics
./manage.py compilestatic # To compile scss in those statics
Sli's avatar
Sli committed
62
```
Skia's avatar
Skia committed
63

64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
### Misc about development

#### Controlling the rights

When you need to protect an object, there are three levels:
  * Editing the object properties
  * Editing the object various values
  * Viewing the object

Now you have many solutions in your model:
  * You can define a `is_owned_by(self, user)`, a `can_be_edited_by(self, user)`, and/or a `can_be_viewed_by(self, user)`
    method, each returning True is the user passed can edit/view the object, False otherwise.   
    This allows you to make complex request when the group solution is not powerful enough.    
    It's useful too when you want to define class-wide permissions, e.g. the club members, that are viewable only for
    Subscribers.
  * You can add an `owner_group` field, as a ForeignKey to Group.  Second is an `edit_groups` field, as a ManyToMany to
    Group, and third is a `view_groups`, same as for edit.

Finally, when building a class based view, which is highly advised, you just have to inherit it from CanEditPropMixin,
CanEditMixin, or CanViewMixin, which are located in core.views. Your view will then be protected using either the
appropriate group fields, or the right method to check user permissions.

Skia's avatar
Skia committed
86 87
#### Counting the number of line of code

88 89 90
```bash
sudo apt install cloc
cloc --exclude-dir=doc,env .
Skia's avatar
Skia committed
91
```
92

Skia's avatar
Skia committed
93 94 95 96 97 98 99 100
#### Updating doc/SYNTAX.md

If you make an update in the Markdown syntax parser, it's good to document
update the syntax reference page in `doc/SYNTAX.md`. But updating this file will
break the tests if you don't update the corresponding `doc/SYNTAX.html` file at
the same time.  
To do that, simply run `./manage.py markdown > doc/SYNTAX.html`,
and the tests should pass again.
101 102