Merge branch 'update-docs' into dev
This commit is contained in:
Sam
commit
b398ffe243
@ -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
|
||||
```
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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>`__).
|
||||
@ -3,7 +3,6 @@ Troubleshooting
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Endpoints:
|
||||
|
||||
administrator
|
||||
user
|
||||
|
||||
@ -182,16 +182,19 @@
|
||||
</dl>
|
||||
</li>
|
||||
</ul>
|
||||
<p>Logo, sports and weather icons are made by <a class="reference external" href="https://www.freepik.com/">Freepik</a> from <a class="reference external" href="https://www.flaticon.com/">www.flaticon.com</a>.</p>
|
||||
<div class="line-block">
|
||||
<div class="line">Logo, some sports and weather icons are made by <a class="reference external" href="https://www.freepik.com/">Freepik</a> from <a class="reference external" href="https://www.flaticon.com/">www.flaticon.com</a>.</div>
|
||||
<div class="line">FitTrackee also uses icons from <a class="reference external" href="https://forkaweso.me">Fork Awesome</a>.</div>
|
||||
</div>
|
||||
<section id="prerequisites">
|
||||
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p>PostgreSQL database (10+)</p></li>
|
||||
<li><p>Redis for task queue</p></li>
|
||||
<li><p>Python 3.7+</p></li>
|
||||
<li><p><a class="reference external" href="https://poetry.eustace.io">Poetry</a> (for installation from sources only)</p></li>
|
||||
<li><p>API key from <a class="reference external" href="https://darksky.net/dev">Dark Sky</a> [not mandatory]</p></li>
|
||||
<li><p>PostgreSQL database (10+)</p></li>
|
||||
<li><p>SMTP provider</p></li>
|
||||
<li><p>Redis for task queue (to send emails)</p></li>
|
||||
<li><p>API key from <a class="reference external" href="https://darksky.net/dev">Dark Sky</a> [not mandatory]</p></li>
|
||||
<li><p><a class="reference external" href="https://poetry.eustace.io">Poetry</a> (for installation from sources only)</p></li>
|
||||
<li><p><a class="reference external" href="https://yarnpkg.com">Yarn</a> (for development only)</p></li>
|
||||
<li><p>Docker and Docker Compose (for development or evaluation purposes)</p></li>
|
||||
</ul>
|
||||
@ -312,8 +315,8 @@ deployment method.</p>
|
||||
<div class="line">Database URL with username and password, must be initialized in production environment.</div>
|
||||
<div class="line">For example in dev environment : <code class="docutils literal notranslate"><span class="pre">postgresql://fittrackee:fittrackee@localhost:5432/fittrackee</span></code></div>
|
||||
</div>
|
||||
<div class="admonition danger">
|
||||
<p class="admonition-title">Danger</p>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<div class="line-block">
|
||||
<div class="line">Since <a class="reference external" href="https://docs.sqlalchemy.org/en/14/changelog/changelog_14.html#change-3687655465c25a39b968b4f5f6e9170b">SQLAlchemy update (1.4+)</a>,
|
||||
engine URL should begin with <cite>postgresql://</cite>.</div>
|
||||
@ -458,6 +461,12 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
|
||||
<li><p>with SSL: <code class="docutils literal notranslate"><span class="pre">smtp://username:password@smtp.example.com:465/?ssl=True</span></code></p></li>
|
||||
<li><p>with STARTTLS: <code class="docutils literal notranslate"><span class="pre">smtp://username:password@smtp.example.com:587/?tls=True</span></code></p></li>
|
||||
</ul>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<div class="line-block">
|
||||
<div class="line">If the email URL is invalid, the application may not start.</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in version 0.5.3.</span></p>
|
||||
</div>
|
||||
@ -465,6 +474,19 @@ see <a class="reference external" href="https://docs.sqlalchemy.org/en/13/core/p
|
||||
<div class="line">Credentials can be omitted: <code class="docutils literal notranslate"><span class="pre">smtp://smtp.example.com:25</span></code>.</div>
|
||||
<div class="line">If <code class="docutils literal notranslate"><span class="pre">:<port></span></code> is omitted, the port defaults to 25.</div>
|
||||
</div>
|
||||
<div class="admonition warning">
|
||||
<p class="admonition-title">Warning</p>
|
||||
<div class="line-block">
|
||||
<div class="line">Since 0.6.0, newly created accounts must be confirmed (an email with confirmation instructions is sent after registration).</div>
|
||||
</div>
|
||||
</div>
|
||||
<p>Emails sent by FitTrackee are:</p>
|
||||
<ul class="simple">
|
||||
<li><p>account confirmation instructions</p></li>
|
||||
<li><p>password reset request</p></li>
|
||||
<li><p>email change (to old and new email adresses)</p></li>
|
||||
<li><p>password change</p></li>
|
||||
</ul>
|
||||
</section>
|
||||
<section id="map-tile-server">
|
||||
<h3>Map tile server<a class="headerlink" href="#map-tile-server" title="Permalink to this headline">¶</a></h3>
|
||||
@ -688,7 +710,7 @@ database credentials</strong>):</p></li>
|
||||
<section id="id2">
|
||||
<h3>From PyPI<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
|
||||
<ul class="simple">
|
||||
<li><p>Activate the virtualenv</p></li>
|
||||
<li><p>Stop the application and activate the virtualenv</p></li>
|
||||
<li><p>Upgrade with pip</p></li>
|
||||
</ul>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ pip install -U fittrackee
|
||||
@ -904,8 +926,7 @@ server {
|
||||
<div class="versionadded">
|
||||
<p><span class="versionmodified added">New in version 0.4.4.</span></p>
|
||||
</div>
|
||||
<p>For evaluation purposes , docker files are available,
|
||||
installing <strong>FitTrackee</strong> from <strong>sources</strong>.</p>
|
||||
<p>For evaluation purposes, docker files are available, installing <strong>FitTrackee</strong> from <strong>sources</strong>.</p>
|
||||
<ul class="simple">
|
||||
<li><p>To install <strong>FitTrackee</strong> with database initialisation and run the application and dramatiq workers:</p></li>
|
||||
</ul>
|
||||
|
||||
File diff suppressed because one or more lines are too long
@ -132,13 +132,20 @@
|
||||
<h1>Administrator<a class="headerlink" href="#administrator" title="Permalink to this headline">¶</a></h1>
|
||||
<section id="fittrackee-fails-to-start">
|
||||
<h2><cite>FitTrackee fails to start</cite><a class="headerlink" href="#fittrackee-fails-to-start" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><p>Check the database URL in <a class="reference external" href="../installation.html#envvar-DATABASE_URL">Environment variables</a> if the following error is displayed in <strong>gunicorn</strong> logs:</p></li>
|
||||
</ul>
|
||||
<ul>
|
||||
<li><p>Check the database URL in <a class="reference external" href="../installation.html#envvar-DATABASE_URL">environment variables</a> if the following error is displayed in <strong>gunicorn</strong> logs:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sqlalchemy</span><span class="o">.</span><span class="n">exc</span><span class="o">.</span><span class="n">NoSuchModuleError</span><span class="p">:</span> <span class="n">Can</span><span class="s1">'t load plugin: sqlalchemy.dialects:postgres</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>It must start with <cite>postgresql://</cite> (engine URLs starting with <cite>postgres://</cite> are no longer supported).</p>
|
||||
</li>
|
||||
<li><p>Check the email URL in <a class="reference external" href="../installation.html#envvar-EMAIL_URL">environment variables</a> if the following error is displayed in <strong>gunicorn</strong> logs:</p>
|
||||
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">fittrackee</span><span class="o">.</span><span class="n">emails</span><span class="o">.</span><span class="n">exceptions</span><span class="o">.</span><span class="n">InvalidEmailUrlScheme</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>A valid <code class="docutils literal notranslate"><span class="pre">EMAIL_URL</span></code> must be provided (see <a class="reference external" href="../installation.html#emails">emails</a>).</p>
|
||||
</li>
|
||||
</ul>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
|
||||
@ -128,7 +128,6 @@
|
||||
<section id="troubleshooting">
|
||||
<h1>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="toctree-wrapper compound">
|
||||
<p class="caption" role="heading"><span class="caption-text">Endpoints:</span></p>
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="administrator.html">Administrator</a><ul>
|
||||
<li class="toctree-l2"><a class="reference internal" href="administrator.html#fittrackee-fails-to-start"><cite>FitTrackee fails to start</cite></a></li>
|
||||
|
||||
@ -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:
|
||||
|
||||
|
||||
@ -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>`__).
|
||||
@ -3,7 +3,6 @@ Troubleshooting
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Endpoints:
|
||||
|
||||
administrator
|
||||
user
|
||||
|
||||
Loading…
Reference in New Issue
Block a user