Improve documentation for sensitivity module (refs #3876)

docs/changelog.rst

@@ -12,6 +12,7 @@ CHANGELOG
 **Documentation**
 
 - Improve PostgreSQL upgrade documentation
+- Integration of sensitivity module notices (import and public api usage)
 
 **Bug fixes**
 

docs/install/advanced-configuration.rst

@@ -806,6 +806,12 @@ After installing Outdoor module, you have to add permissions to your user groups
 Sensitive areas
 ~~~~~~~~~~~~~~~
 
+.. note::
+    The sensitivity module was developed as part of the Biodiv'Sports project to provide a central platform for sensitive areas. 
+
+    The official address of the Geotrek instance of the Biodiv'Sports project is: https://biodiv-sports.fr, and is the base URL for the following API URLs.
+
+
 .. envvar:: INSTALLED_APPS for Sensitive areas
 
     In order to enable sensitivity module, in the custom settings file, add the following code:
@@ -815,15 +821,13 @@ Sensitive areas
         INSTALLED_APPS += ('geotrek.sensitivity', )
 
 
-You can insert rules of sensitive area with these commands :
+    You can insert rules of sensitive area with these commands:
 
-::
+    .. code-block:: bash
 
-    sudo geotrek loaddata /opt/geotrek-admin/lib/python*/site-packages/geotrek/sensitivity/fixtures/rules.json
-    cp -r /opt/geotrek-admin/lib/python*/site-packages/geotrek/sensitivity/fixtures/upload/rules/ /opt/geotrek-admin/var/media/upload/
+        sudo geotrek loaddata /opt/geotrek-admin/lib/python*/site-packages/geotrek/sensitivity/fixtures/rules.json
+        cp -r /opt/geotrek-admin/lib/python*/site-packages/geotrek/sensitivity/fixtures/upload/rules/ /opt/geotrek-admin/var/media/upload/
 
-Settings
-'''''''''
 
 The following settings are related to sensitive areas:
 
@@ -857,62 +861,7 @@ The following settings are related to sensitive areas:
     # Take care if you change this value after adding data. You should update buffered geometry in sql.
     ``` UPDATE sensitivity_sensitivearea SET geom_buffered = ST_BUFFER(geom, <your new value>); ```
 
-
-Import from https://biodiv-sports.fr
-''''''''''''''''''''''''''''''''''''''
-
-In user interface, in the top-right menu, clic on "Imports" and choose "Biodiv'Sports".
-
-On command line, run
-
-.. code-block:: bash
-
-    sudo geotrek import geotrek.sensitivity.parsers.BiodivParser
-
-
-Import from shapefile
-'''''''''''''''''''''''
-
-In user interface, in the top-right menu, go to Imports and choose "Shapefile zone sensible espèce"
-or "Shapefile zone sensible réglementaire".
-
-.. note::
-  The file must be a zip containing all the shapefile extensions (.shp, .shx, .prj, .dbf, .cpg)
-
-.. figure:: ../images/advanced-configuration/import_shapefile.png
-   :alt: Import shapefile in user interface
-   :align: center
-
-   Import shapefile in user interface
-
-
-On command line, run:
-
-.. code-block:: bash
-
-    sudo geotrek import geotrek.sensitivity.parsers.SpeciesSensitiveAreaShapeParser <file.shp>
-
-or:
-
-.. code-block:: bash
-
-    sudo geotrek  import geotrek.sensitivity.parsers.RegulatorySensitiveAreaShapeParser <file.shp>.
-
-Attributes for "zones espèces sensibles" are:
-
-* ``espece`` : species name. Mandatory. A species with this name must have been previously created.
-* ``contact`` : contact (text or HTML format). Optional.
-* ``descriptio`` : description (text or HTML format). Optional.
-
-Attributes for "zones sensibles réglementaires" are:
-
-* ``name``: zone name.
-* ``contact`` : contact (text or HTML format). Optional.
-* ``descriptio`` : description (text or HTML format). Optional.
-* ``periode`` : month numbers of zone occupation, separated by comas, without spaces (ex. « 6,7,8 » for june, july and august)
-* ``pratiques`` : sport practices names, separated by comas, without spaces (ex. « Terrestre,Aérien »). A sport practice with this name must have been previously created.
-* ``url`` : card url. Optional.
-
+see :ref:`import-sensitive-areas` to import data.
 
 Feedback reports settings
 -------------------------

docs/install/import.rst

@@ -334,12 +334,103 @@ edit ``/opt/geotrek-admin/var/conf/parsers.py`` file with the following content:
 
 Then run in command line
 
-::
+.. code-block:: bash
 
     sudo geotrek import DemoGeotrekTrekParser
 
 Treks are now imported into your own instance.
 
+.. _import-sensitive-areas:
+
+Import sensitive areas
+======================
+
+Import from https://biodiv-sports.fr
+------------------------------------
+
+It is possible to import automatically data from Biodiv'Sport. To do so, you just need to follow those steps:
+
+- Click on the **user link** at top right, then on **Imports**,
+- Under the section **Data to import from network**, select **Biodiv'Sports**
+- Click on **Import**,
+- Wait a few seconds,
+- The import progress is displayed on the right
+
+When the import is done, you can check the Sensitivity module in Geotrek and you'll find data inside.
+
+It is also possible to import sensitive areas through command line:
+
+.. code-block :: bash
+
+    sudo geotrek import geotrek.sensitivity.parsers.BiodivParser
+
+.. warning:: 
+  If you don't see any data in your area, it means that Biodiv'Sports does not contains data for your territory. 
+  Then it is widely recommended to add your data directly into Biodiv'Sports, as it will be available for 
+  multiple users, and then retrieve them into your Geotrek instance. To import data in Biodiv'Sports 
+  go visit its website: https://biodiv-sports.fr
+
+
+Import from shapefile
+---------------------
+
+Imported data must be in standard ESRI shapefile format. 
+The various Shapefile files (``.shp``, ``.shx``, ``.dbf``, ``.prj``, *etc*.) must be assembled in a zip archive.
+
+.. warning::
+  Please note! The description field name ``descriptio`` does not include the final ``n``, as field names are limited to 10 characters in shapefiles.
+
+Attribute data for sensitive areas species
+
+- ``espece``: Species name. Mandatory. A species with this name must first have been created in Biodiv'sports. Otherwise, import of the line will fail.
+- ``contact``: Contact in text or HTML format. *Optional*.
+- ``descriptio``: Description in text or HTML format. *Optional*. 
+
+.. warning::
+  Species name must strictly respect the species name string (accentuation, case and punctuation).
+
+Attribute data for regulatory sensitive areas:
+
+- ``name`` : Area name
+- ``contact`` : Contact in text or HTML format. *Optional*.
+- ``descriptio`` : Description in text or HTML format. *Optional*.
+- ``periode``: Numbers of the months in which the area is occupied, **comma separated** and **without spaces** (e.g. ``6,7,8`` for June, July and August).
+- ``practices``: Names of practices, separated by commas, without spaces (e.g. ``Terrestre,Aerien,Vertical``), see :envvar:`Sport practices`. Otherwise, the line import will fail.
+- ``url`` : Record url. *Optional*.
+
+Import from web interface
+
+- Click on the **user link** at top right, then on **Imports**,
+- Select the type of data to be imported (**species** or **regulatory area**),
+- Select the *.zip* file to be imported,
+- Select the correct encoding (``UTF8`` or ``Windows-1252``)
+- Click on **Import**,
+- Wait a few seconds,
+- The import progress is displayed on the right,
+- Click on **Display report** to see any unimported lines.
+
+.. figure:: ../images/advanced-configuration/import_shapefile.png
+   :alt: Import shapefile in user interface
+   :align: center
+
+   Import shapefile in user interface
+
+On command line, run:
+
+.. code-block:: bash
+
+    sudo geotrek import geotrek.sensitivity.parsers.SpeciesSensitiveAreaShapeParser <file.shp>
+
+or:
+
+.. code-block:: bash
+
+    sudo geotrek  import geotrek.sensitivity.parsers.RegulatorySensitiveAreaShapeParser <file.shp>.
+
+
+.. warning:: 
+  Relaunching an import **with the same file** will create duplicates.
+
 
 Import other datas from a file
 ==============================

docs/usage/apis.rst

@@ -105,3 +105,143 @@ L'API permet de connecter une instance Geotrek pour importer des itinéraires ve
 Les randonnées VTT, trail, vélo et les tours itinérants sont également intégrés dans la passerelle.
 
 Pour plus d'information, se référer à la documentation en ligne de `Sitourisme <https://github.com/GeotrekCE/Sitourisme#sitourisme-paca-api>`_. 
+
+
+Sensitivity module (or Biodiv'Sports)
+-------------------------------------
+
+.. note::
+
+  You can play with API using Biodiv'Sports widget tool: https://biodivsports-widget.lpo-aura.org/
+
+The Geotrek API provides a set of parameters that can be used to filter and sort data. There is a Swagger documentation (see :ref:`advanced-configuration-section` to enable it on your instance if needed) existing to test and browse those parameters that can be found at this address: ``/api/v2/``.
+
+This section focuses on some common parameters useful to work with sensitivity information and gives details about some endpoints.
+
+
+.. envvar:: Commons parameters
+
+
+   If ``language`` parameter is provided, API returns directly translated fields, else, a dictionnary of traductions is returned
+
+   e.g. ``/api/v2/sensitivearea_practice/1/?``
+
+
+   .. code-block:: JSON
+
+      {
+         "id":1,
+         "name":{
+         "fr":"Terrestre",
+         "en":"Land",
+         "it":null
+         }
+      }
+
+
+   e.g. ``/api/v2/sensitivearea_practice/1/?language=en``
+
+
+   .. code-block:: JSON
+
+      {
+         "id":1,
+         "name":"Land"
+      }
+
+
+.. envvar:: Sport practices
+
+   List of sport practices
+
+   ``/api/v2/sensitivearea_practice/``
+
+   e.g. https://biodiv-sports.fr/api/v2/sensitivearea_practice/
+
+
+.. envvar:: Sensitive areas
+
+   List of sensitive areas
+
+   ``/api/v2/sensitivearea/``
+
+   The default output format is ``json``. To obtain output in ``geojson`` format, simply add the ``format=geojson`` parameter.
+
+   ``/api/v2/sensitivearea/?format=geojson`` 
+
+   e.g. https://biodiv-sports.fr/api/v2/sensitivearea/?format=geojson
+
+   **Filtering data**
+
+   Data can be filtered through these parameters:
+
+   - ``language`` : API language (see :envvar:`Commons parameters`)
+
+   - Expected values: ``fr``, ``en``, ``es`` or ``it``
+   - e.g. ``/api/v2/sensitivearea/?language=fr``
+
+   - ``period`` : Sensitivy period (months list)
+
+   - Expected values: List of month numbers (from 1 to 12), comma separated
+   - e.g. ``/api/v2/sensitivearea/?period=4,5,6,7``
+
+   - ``practices`` : Sport practices
+
+   - Expected values: List of practices ids (see :envvar:`Sport practices`)
+   - e.g. ``/api/v2/sensitivearea/?practices=1,2``
+
+   - ``structure`` : Organization that declared the sensitive area. 
+
+   - Expected values: List of structures ids
+   - e.g. ``/api/v2/sensitivearea/?structures=1,2``
+
+   - ``in_bbox``
+
+   - Expected values: List of bbox coordinates (respectively longitude and latitude South-West then North-East corner), comma separated.
+   - e.g. ``/api/v2/sensitivearea/?in_bbox=5.0,45.0,6.0,46.0``
+
+   Full example https://biodiv-sports.fr/api/v2/sensitivearea/?format=geojson&language=fr&practices=1,2&period=4,5,6,7&in_bbox=5.0,45.0,6.0,46.0
+
+   **Filtering fields**
+
+   - ``fields``: List of expected fields (see :ref:`Field Descriptions <FielDesc>`)
+
+   - Expected values: List of field names, comma separated
+   - e.g. ``/api/v2/sensitivearea/?fields=name,geometry``
+
+   - ``omit``: List of excluded fields (see :ref:`Field Descriptions <FielDesc>`)
+
+   - Expected values: List of field names, comma separated
+   - e.g. ``/api/v2/sensitivearea/?omit=name,geometry``
+
+   .. warning::
+      **GeoJSON** format expect at least `id` and `geometry` fields.
+
+   .. _FielDesc:
+
+   **Field descriptions**
+
+
+   - ``id`` : local unique identifier of the sensitive area (integer).
+   - ``name`` : Area name (string).
+   - ``description`` : Area description (string in HTML format).
+   - ``period`` : Area occupancy for each of the 12 months of the year (ordered array of 12 Booleans).
+   - ``contact`` : Contact for further information about the sensitive area (string in HTML format).
+   - ``practices``: sports practices concerned by the hotspot (array of identifiers).
+   - ``info_url`` : URL containing further information about the area (URL).
+   - ``structure`` : Structure or acronyme that provided information on the area (string).
+   - ``elevation`` : Elevation used to define area sensitivity volume (globally elevation, buffer radius for areas declared as Point).
+   - ``geometry`` : Area GeoJSON geometry. Type is always "Polygon".
+   - ``species_id``: species identifier or null for regulatory areas.
+   - ``kml_url`` : URL of the downloadable KML file representing this regulatory zone.
+   - ``openair_url`` : URL of the downloadable OpenAir file representing the regulatory zone (available only for aerial activities).
+   - ``attachment`` : List of area attachment files.
+   - ``rules`` : List of regulatory rules.
+   - ``update_datetime``: last update timestamp.
+   - ``create_datetime``: create timestamp.
+
+.. note::
+   Species informations are commons for each species areas sharing the same ``species_id`` value, also share the same values for the ``name``, ``period``, ``practices`` and ``info_url`` fields.
+
+
+