Improved the 'CONTRIBUTING' documentation

CONTRIBUTING.rst

@@ -8,11 +8,40 @@ The repository is hosted at `gitlab.com/yaal/canaille <https://gitlab.com/yaal/c
 Development environment
 -----------------------
 
+You can either run the demo locally or with docker.
+After having launched the demo you have access to several services:
+
+- A canaille server at `localhost:5000 <http://localhost:5000>`_
+- A dummy client at `localhost:5001 <http://localhost:5001>`_
+- Another dummy client at `localhost:5002 <http://localhost:5002>`_
+
+The canaille server has some default users:
+
+- A regular user which login and password are **user**;
+- A moderator user which login and password are **moderator**;
+- An admin user which admin and password are **admin**;
+- A new user which login is **james**. This user has no password yet,
+  and his first attempt to log-in would result in sending a password initialization
+  email (if a smtp server is configurated).
+
+
+Docker environment
+~~~~~~~~~~~~~~~~~~
+
+If you want to develop with docker, use:
+
 .. code-block:: console
 
-    python3 setup.py compile_catalog
-    cd demo
-    ./run.sh # or `docker-compose up` to run it with docker
+    cd demo && docker-compose up
+
+Local environment
+~~~~~~~~~~~~~~~~~
+
+If you want to develop locally, use:
+
+.. code-block:: console
+
+    ./demo/run.sh
 
 .. warning ::
 
@@ -25,17 +54,14 @@ Development environment
         sudo apt install --yes apparmor-utils
         sudo aa-complain /usr/sbin/slapd
 
-Then you have access to:
+Populate the database
+~~~~~~~~~~~~~~~~~~~~~
 
-- A canaille server at `localhost:5000 <http://localhost:5000>`_
-- A dummy client at `localhost:5001 <http://localhost:5001>`_
-- Another dummy client at `localhost:5002 <http://localhost:5002>`_
+You can populate the database with randomly generated users and groups with the ``populate`` command:
 
-The canaille server has some default users:
+.. code-block:: console
 
-- A regular user which login and password are **user**;
-- A moderator user which login and password are **moderator**;
-- An admin user which admin and password are **admin**.
+    env CONFIG=conf/canaille.toml poetry run canaille populate
 
 Unit tests
 ----------
@@ -81,4 +107,4 @@ The documentation is generated when the tests run:
 
     tox -e doc
 
-The generated documentation is in `./build/sphinx/html/` directory.
+The generated documentation is located at `./build/sphinx/html`.

demo/README.md

@@ -4,50 +4,4 @@ To check out how canaille looks like, or to start contributions, just run the de
 - with `docker-compose up` to install and run it in preconfigured docker containers
 - or with `./run.sh` to install it natively in a virtual environment and run it locally!
 
-# Prerequisites for native demo installation
-
-You need to have `OpenLDAP` somewhere in your system.
-
-You need to install it with your distro packages *(for instance `sudo apt install slapd
-ldap-utils` with Ubuntu)*. It is not required to launch the system ldap service.
-
-Canaille depends on [python-ldap](https://github.com/python-ldap/python-ldap), and this package needs
-some headers to be installed on your system to be built. For instance on Ubuntu you can install this:
-`sudo apt install libsasl2-dev python-dev libldap2-dev libssl-dev`. More info
-[on this SO ticket](https://stackoverflow.com/questions/4768446/i-cant-install-python-ldap).
-
-## Apparmor
-
-On Ubuntu systems, apparmor prevents *slapd* from accessing files that are not in the standard
-OpenLDAP installation. This may result in canaille being impossible to launch. To fix this you
-can pass slapd in complain mode:
-
-```bash
-sudo apt install --yes apparmor-utils
-sudo aa-complain /usr/sbin/slapd
-```
-
-# Run the demo
-
-Then you have access to:
-
-- A canaille server at http://localhost:5000
-- A dummy client at http://localhost:5001
-- Another dummy client at http://localhost:5002, for which consent is already granted for users
-
-The canaille server has some default users:
-
-- A regular user which login and password are **user**;
-- A moderator user which login and password are **moderator**;
-- An admin user which login and password are **admin**.
-- A new user which login is **james**. This user has no password yet,
-  and his first attempt to log-in would result in sending a password initialization
-  email (if a smtp server is configurated).
-
-# Populate the database
-
-You can populate the database with randomly generated users and groups with the ``populate`` command:
-
-```bash
-env CONFIG=conf/canaille.toml poetry run canaille populate
-```
+Please check the details on [the documentation](https://canaille.readthedocs.io/en/latest/contributing.html).

demo/run.sh

@@ -21,4 +21,7 @@ if ! type poetry > /dev/null 2>&1; then
 fi
 
 poetry install --with demo --without dev
-env "PWD=$DIR" poetry run honcho start
+
+pushd "$DIR" > /dev/null 2>&1 || exit
+env poetry run honcho start
+popd || exit