mirror of
https://github.com/ae-utbm/sith.git
synced 2024-11-22 06:03:20 +00:00
documentation: remove Doxygen, include README into doc update tech and install
This commit is contained in:
parent
dd49d71cb7
commit
8dcade6890
GPG Key ID:
E7245548C53F904B
103
README.md
103
README.md
@ -1,103 +0,0 @@
|
||||
[](https://ae-dev.utbm.fr/ae/Sith/commits/master)
|
||||
[](https://ae-dev.utbm.fr/ae/Sith/commits/master)
|
||||
[](https://github.com/ambv/black)
|
||||
[](https://ae-dev.zulipchat.com)
|
||||
[](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.
|
||||
|
||||
|
||||
82
README.rst
Normal file
82
README.rst
Normal file
@ -0,0 +1,82 @@
|
||||
.. 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.
|
||||
|
||||
|
||||
@ -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
|
||||
~~~~~~~~~~
|
||||
|
||||
|
||||
@ -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
|
||||
apps/core
|
||||
|
||||
.. include:: ../README.rst
|
||||
:start-after: body
|
||||
|
||||
@ -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
|
||||
./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
|
||||
Loading…
Reference in New Issue
Block a user