Skip to content

GitLab

Verified Commit 8dcade68 authored by Sli's avatar Sli
Browse files

documentation: remove Doxygen, include README into doc update tech and install

parent dd49d71c
Expand all Hide whitespace changes
Inline Side-by-side
Doxyfile deleted 100644 → 0
View file @ dd49d71c
This diff is collapsed.
README.md deleted 100644 → 0
View file @ dd49d71c
[![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)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
[![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://ae-dev.zulipchat.com)
[![Documentation Status](https://readthedocs.org/projects/sith-ae/badge/?version=latest)](https://sith-ae.readthedocs.io/?badge=latest)
## Sith AE
### Dependencies:
See requirements.txt
You may need to install some dev libraries like `libmysqlclient-dev`, `libssl-dev`, `libjpeg-dev`, `python3-xapian`, or `zlib1g-dev` to install all the
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:
```bash
sudo apt install libmysqlclient-dev libssl-dev libjpeg-dev zlib1g-dev python3-dev libffi-dev python3-dev libgraphviz-dev pkg-config python3-xapian gettext
```
On macos, you will need homebrew
```bash
brew install xapian
```
The development is done with sqlite, but it is advised to set a more robust DBMS for production (Postgresql for example)
### Get started
To start working on the project, just run the following commands:
```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
```
To start the simple development server, just run `python3 manage.py runserver`
For more informations, check out the CONTRIBUTING.md file.
### 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
### Generating documentation
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.
### Collecting statics for production:
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 :
```bash
./manage.py collectstatic # To collect statics
./manage.py compilestatic # To compile scss in those statics
```
### 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.
#### Counting the number of line of code
```bash
sudo apt install cloc
cloc --exclude-dir=doc,env .
```
#### 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.
README.rst 0 → 100644
View file @ 8dcade68
.. image:: https://ae-dev.utbm.fr/ae/Sith/badges/master/pipeline.svg
:target: https://ae-dev.utbm.fr/ae/Sith/commits/master
:alt: pipeline status
.. image:: https://ae-dev.utbm.fr/ae/Sith/badges/master/coverage.svg
:target: https://ae-dev.utbm.fr/ae/Sith/commits/master
:alt: coverage report
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/ambv/black
:alt: Code style: black
.. image:: https://img.shields.io/badge/zulip-join_chat-brightgreen.svg
:target: https://ae-dev.zulipchat.com
:alt: project chat
.. image:: https://readthedocs.org/projects/sith-ae/badge/?version=latest
:target: https://sith-ae.readthedocs.io/?badge=latest
:alt: Documentation Status
.. body
Sith AE
=======
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
Collecting statics for production:
----------------------------------
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 :
.. sourcecode:: bash
./manage.py collectstatic # To collect statics
./manage.py compilestatic # To compile scss in those statics
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.
Counting the number of line of code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. sourcecode:: bash
sudo apt install cloc
cloc --exclude-dir=doc,env .
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.
doc/about/tech.rst
View file @ 8dcade68
......@@ -133,6 +133,14 @@ GitLab est une alternative libre à GitHub. C'est une plate-forme avec interface
C'est au travers de cette plate-forme que le Sith de l'AE est géré, sur une instance hébergée directement sur nos serveurs.
Sentry
~~~~~~
| `Site officiel <https://sentry.io>`__
| `Instance de l'AE <https://ae2.utbm.fr`__
Sentry est une plate-forme libre qui permet de se tenir informer des bugs qui ont lieu sur le site. À chaque crash du logiciel (erreur 500), une erreur est envoyée sur la plate-forme et est indiqué précisément à quelle ligne de code celle-ci a eu lieu, à quelle heure, combien de fois, avec quel navigateur la page a été visitée et même éventuellement un commentaire de l'utilisateur qui a rencontré le bug.
Virtualenv
~~~~~~~~~~
......
doc/index.rst
View file @ 8dcade68
......@@ -6,6 +6,9 @@
Bienvenue sur la documentation du Sith de l'AE
==============================================
.. include:: ../README.rst
:end-before: body
.. toctree::
:maxdepth: 2
:caption: À propos du projet:
......@@ -23,4 +26,7 @@ Bienvenue sur la documentation du Sith de l'AE
:maxdepth: 3
:caption: Documentation des apps:
apps/core
\ No newline at end of file
apps/core
.. include:: ../README.rst
:start-after: body
doc/start/install.rst
View file @ 8dcade68
......@@ -13,15 +13,18 @@ Certaines dépendances sont nécessaires niveau système :
* python3-xapian
* zlib1g-dev
* python3
* mysql-client (pour migrer de l'ancien site)
Sur ubuntu :
Sur Ubuntu
~~~~~~~~~~
.. sourcecode:: bash
sudo apt install libmysqlclient-dev libssl-dev libjpeg-dev zlib1g-dev python3-dev libffi-dev python3-dev libgraphviz-dev pkg-config python3-xapian gettext git
sudo pip3 install virtualenv
Sur macos :
Sur MacOS
~~~~~~~~~
Pour installer les dépendances, il est fortement recommandé d'installer le gestionnaire de paquets `homebrew <https://brew.sh/index_fr>`__.
......@@ -65,4 +68,17 @@ Il faut toujours avoir préalablement activé l'environnement virtuel comme fait
.. sourcecode:: bash
./manage.py runserver
\ No newline at end of file
./manage.py runserver
Le serveur est alors accessible à l'adresse `http://localhost:8000 <http://localhost:8000`__.
Générer la documentation
------------------------
La documentation est automatiquement mise en ligne sur readthedocs à chaque envoi de code sur GitLab.
Pour l'utiliser en local ou globalement pour la modifier, il existe une commande du site qui génère la documentation et lance un serveur la rendant accessible à l'adresse `http://localhost:8080 <http://localhost:8080>`__.
.. sourcecode:: bash
./manage.py documentation
\ No newline at end of file
Supports Markdown
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