mirror of
https://github.com/ae-utbm/sith.git
synced 2024-11-22 14:13:21 +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.
|
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
|
Virtualenv
|
||||||
~~~~~~~~~~
|
~~~~~~~~~~
|
||||||
|
|
||||||
|
|||||||
@ -6,6 +6,9 @@
|
|||||||
Bienvenue sur la documentation du Sith de l'AE
|
Bienvenue sur la documentation du Sith de l'AE
|
||||||
==============================================
|
==============================================
|
||||||
|
|
||||||
|
.. include:: ../README.rst
|
||||||
|
:end-before: body
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:caption: À propos du projet:
|
:caption: À propos du projet:
|
||||||
@ -23,4 +26,7 @@ Bienvenue sur la documentation du Sith de l'AE
|
|||||||
:maxdepth: 3
|
:maxdepth: 3
|
||||||
:caption: Documentation des apps:
|
: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
|
* python3-xapian
|
||||||
* zlib1g-dev
|
* zlib1g-dev
|
||||||
* python3
|
* python3
|
||||||
|
* mysql-client (pour migrer de l'ancien site)
|
||||||
|
|
||||||
Sur ubuntu :
|
Sur Ubuntu
|
||||||
|
~~~~~~~~~~
|
||||||
|
|
||||||
.. sourcecode:: bash
|
.. 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 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
|
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>`__.
|
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
|
.. 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