update documentation

CONTRIBUTING.md

@@ -20,6 +20,9 @@ The **GitHub** repository contains:
 - tests,
 - documentation (source and build).
 
+Continuous integration workflows run on **Github Actions** platform (on **push** and **pull requests**).
+
+
 ### How to install FitTrackee
 
 see [Installations instructions](https://samr1.github.io/FitTrackee/installation.html)
@@ -48,7 +51,7 @@ Please make your changes from the development branch (`dev`).
     ```
   * Check the downgrade migration.
   
-* Run checks (lint, typecheck and tests).
+* Run checks (lint, type check and unit tests).
   ```shell
   $ make check-all
   ```
@@ -59,9 +62,9 @@ Please make your changes from the development branch (`dev`).
 
 * If needed, add or update tests.
 
-* If needed, update documentation.
+* If needed, update documentation (no need to build documentation, it will be done when releasing).
 
-* If code contains client changes, you can generate a build, in a **separate commit** to ease code review.
+* If updated code contains client-side changes, you can generate a build, in a **separate commit** to ease code review (or to easily drop it in case of conflicts when updating your branch).
   ```shell
   $ make build-client
   ```

docsrc/source/installation.rst

@@ -14,17 +14,18 @@ This application is written in Python (API) and Typescript (client):
     - `Leaflet <https://leafletjs.com/>`__ to display map
     - `Chart.js <https://www.chartjs.org/>`__ to display charts with elevation and speed
 
-Logo, sports and weather icons are made by `Freepik <https://www.freepik.com/>`__ from `www.flaticon.com <https://www.flaticon.com/>`__.
+| Logo, some sports and weather icons are made by `Freepik <https://www.freepik.com/>`__ from `www.flaticon.com <https://www.flaticon.com/>`__.
+| FitTrackee also uses icons from `Fork Awesome <https://forkaweso.me>`__.
 
 Prerequisites
 ~~~~~~~~~~~~~
 
--  PostgreSQL database (10+)
--  Redis for task queue
 -  Python 3.7+
--  `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
--  API key from `Dark Sky <https://darksky.net/dev>`__ [not mandatory]
+-  PostgreSQL database (10+)
 -  SMTP provider
+-  Redis for task queue (to send emails)
+-  API key from `Dark Sky <https://darksky.net/dev>`__ [not mandatory]
+-  `Poetry <https://poetry.eustace.io>`__ (for installation from sources only)
 -  `Yarn <https://yarnpkg.com>`__ (for development only)
 -  Docker and Docker Compose (for development or evaluation purposes)
 
@@ -108,7 +109,7 @@ deployment method.
     | Database URL with username and password, must be initialized in production environment.
     | For example in dev environment : ``postgresql://fittrackee:fittrackee@localhost:5432/fittrackee``
 
-    .. danger::
+    .. warning::
         | Since `SQLAlchemy update (1.4+) <https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html#change-3687655465c25a39b968b4f5f6e9170b>`__,
           engine URL should begin with `postgresql://`.
 
@@ -209,12 +210,25 @@ To send emails, a valid ``EMAIL_URL`` must be provided:
 - with SSL: ``smtp://username:password@smtp.example.com:465/?ssl=True``
 - with STARTTLS: ``smtp://username:password@smtp.example.com:587/?tls=True``
 
+.. warning::
+    | If the email URL is invalid, the application may not start.
 
 .. versionadded:: 0.5.3
 
 | Credentials can be omitted: ``smtp://smtp.example.com:25``.
 | If ``:<port>`` is omitted, the port defaults to 25.
 
+.. warning::
+     | Since 0.6.0, newly created accounts must be confirmed (an email with confirmation instructions is sent after registration).
+
+Emails sent by FitTrackee are:
+
+- account confirmation instructions
+- password reset request
+- email change (to old and new email adresses)
+- password change
+
+
 Map tile server
 ^^^^^^^^^^^^^^^
 .. versionadded:: 0.4.0
@@ -423,7 +437,7 @@ Upgrade
 From PyPI
 ^^^^^^^^^
 
-- Activate the virtualenv
+- Stop the application and activate the virtualenv
 
 - Upgrade with pip
 
@@ -444,7 +458,6 @@ From PyPI
 
     $ fittrackee_upgrade_db
 
-
 - Restart the application and task queue workers.
 
 
@@ -647,8 +660,7 @@ Installation
 
 .. versionadded:: 0.4.4
 
-For evaluation purposes , docker files are available,
-installing **FitTrackee** from **sources**.
+For evaluation purposes, docker files are available, installing **FitTrackee** from **sources**.
 
 - To install **FitTrackee** with database initialisation and run the application and dramatiq workers:
 

docsrc/source/troubleshooting/administrator.rst

@@ -5,10 +5,18 @@ Administrator
 `FitTrackee fails to start`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Check the database URL in `Environment variables <../installation.html#envvar-DATABASE_URL>`__ if the following error is displayed in **gunicorn** logs:
+- Check the database URL in `environment variables <../installation.html#envvar-DATABASE_URL>`__ if the following error is displayed in **gunicorn** logs:
 
-.. code::
+  .. code::
 
-   sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres
+     sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:postgres
 
-It must start with `postgresql://` (engine URLs starting with `postgres://` are no longer supported).
+  It must start with `postgresql://` (engine URLs starting with `postgres://` are no longer supported).
+
+- Check the email URL in `environment variables <../installation.html#envvar-EMAIL_URL>`__ if the following error is displayed in **gunicorn** logs:
+
+  .. code::
+
+     fittrackee.emails.exceptions.InvalidEmailUrlScheme
+
+  A valid ``EMAIL_URL`` must be provided (see `emails <../installation.html#emails>`__).

docsrc/source/troubleshooting/index.rst

@@ -3,7 +3,6 @@ Troubleshooting
 
 .. toctree::
    :maxdepth: 2
-   :caption: Endpoints:
 
    administrator
    user