Fix import_geofla withe new file format - update documentation for town import and installation

7 files changed, 120 insertions, 35 deletions

diff --git a/docs/fr/source/_static/annexe-technique-1-export-qgis.png b/docs/fr/source/_static/annexe-technique-1-export-qgis.png
new file mode 100644
index 000000000..2bea47376
--- /dev/null
+++ b/docs/fr/source/_static/annexe-technique-1-export-qgis.png
diff --git a/docs/fr/source/annexe-tech-1-insee-communes.rst b/docs/fr/source/annexe-tech-1-insee-communes.rst
new file mode 100644
index 000000000..4e132669f
--- /dev/null
+++ b/docs/fr/source/annexe-tech-1-insee-communes.rst
@@ -0,0 +1,27 @@
+.. -*- coding: utf-8 -*-
+
+.. _import-regroupements-communes-insee:
+
+==============================================================
+Annexe technique 1 - Import des regroupements de commune INSEE
+==============================================================
+
+:Auteur: Étienne Loks
+:Date: 2020-09-23
+:Copyright: CC-BY 3.0
+
+----------------------------------
+
+L'`INSEE <https://www.insee.fr>`_ met à disposition un fichier permettant de suivre l'évolution des « communes nouvelles » (procédure de regroupement de communes). Au sein de sa base de données, Ishtar gère ces évolutions permettant à la fois d'insérer de nouvelles données pour ces communes nouvelles mais aussi de conserver voire ajouter des données relatives à des communes anciennes maintenant regroupées. Une page sur le site de l'INSEE permet de télécharger ces données au format CSV : `communes nouvelles <https://www.insee.fr/fr/information/2549968>`_.
+
+Ce fichier est importable au sein d'Ishtar.
+
+Pour cela, se connecter sur le serveur hébergeant Ishtar, déposer le fichier CSV que l'on a téléchargé, puis se rendre dans le répertoire d'installation de l'instance concernée. Enfin, lancer la commande suivante (en remplaçant <année> et <chemin vers le fichier CSV> par les valeurs adéquates) :
+
+.. code-block:: bash
+
+    root@ishtar-server:# cd <chemin vers l instance> # exemple : /srv/ishtar/prod_deb
+    root@ishtar-server:# python3 ./manage.py import_insee_comm_csv --year <année> <chemin vers le fichier CSV>
+
+.. note:: L'année attendue est celle de l'année de création des communes nouvelles.
+
diff --git a/docs/fr/source/annexe-tech-2-ign-communes.rst b/docs/fr/source/annexe-tech-2-ign-communes.rst
new file mode 100644
index 000000000..66b161a07
--- /dev/null
+++ b/docs/fr/source/annexe-tech-2-ign-communes.rst
@@ -0,0 +1,44 @@
+.. -*- coding: utf-8 -*-
+
+============================================
+Annexe technique 2 - Import des communes IGN
+============================================
+
+:Auteur: Étienne Loks
+:Date: 2020-09-23
+:Copyright: CC-BY 3.0
+
+----------------------------------
+
+
+L'`IGN <http://www.ign.fr/>`_ met à disposition sous licence libre (`Licence ouverte <https://www.etalab.gouv.fr/wp-content/uploads/2014/05/Licence_Ouverte.pdf>`_) les géométries du découpage administratif du territoire métropolitain français avec une réactualisation annuelle. Au sein d'Ishtar, il est opportun de récupérer le découpage des communes avec leur géométrie associée. On réalise cela en deux temps : récupération des données et export au format CSV, puis import au sein d'Ishtar. Il est nécessaire pour faire cet import d'un accès en ligne de commande au serveur sur lequel est hébergé Ishtar.
+
+
+Récupération des données
+------------------------
+
+Le jeu de données qui nous intéresse est distribué sous le nom ADMIN EXPRESS. Ce jeu de données est disponible en ligne directement sur le site de l'IGN : `ADMIN EXPRESS <https://geoservices.ign.fr/documentation/diffusion/telechargement-donnees-libres.html#admin-express>`_.
+
+Une fois le fichier récupéré, il doit être décompressé (préalablement installer un utilitaire à même de décompresser les archives 7z). Les fichiers qui nous intéressent concernent le shapefile COMMUNE ou COMMUNE_CARTO (géométrie généralisée - moins précise et de fait moins volumineuse). Celui se trouve dans le répertoire `ADMIN-EXPRESS-COG/1_DONNEES_LIVRAISON_<date de livraison>/<zone concernée>/`.
+
+Ce shapefile doit ensuite être ouvert dans QGIS puis exporté au format CSV en n'oubliant pas d'inclure la géométrie au format WKT.
+
+.. image:: _static/annexe-technique-1-export-qgis.png
+
+
+Import dans Ishtar
+------------------
+
+Il ne reste plus qu'à importer dans Ishtar. Pour cela, se connecter sur le serveur hébergeant Ishtar, déposer le fichier CSV que l'on a généré, puis se rendre dans le répertoire d'installation de l'instance concernée. Enfin, lancer la commande suivante (en remplaçant <année> et <chemin vers le fichier CSV> par les valeurs adéquates) :
+
+.. code-block:: bash
+
+    root@ishtar-server:# cd <chemin vers l instance> # exemple : /srv/ishtar/prod_deb
+    root@ishtar-server:# python3 ./manage.py import_geofla_csv --year <année> \
+                                  --srid <code epsg de la projection> <chemin vers le fichier CSV>
+    root@ishtar-server:#  # exemple
+    root@ishtar-server:# python3 ./manage.py import_geofla_csv --year 2019 --srid 4326 /tmp/2019.csv
+
+.. warning:: L'année attendue est celle correspondant à l'année de création pour des communes nouvelles. Le jeu de données d'une année concerne les communes créées l'année précédente ainsi pour le jeu de données 2020, il faut indiquer 2019.
+.. warning:: Si l'on souhaite garder un suivi des regroupements de communes, il est important de procéder à l'import des nouvelles communes (cf. :ref:`import-regroupements-communes-insee`) de l'année concernée depuis les sources INSEE avant de faire l'import des géométries depuis les sources IGN.
+
diff --git a/docs/fr/source/conf.py b/docs/fr/source/conf.py
index a9b5a272b..76839bd7c 100644
--- a/docs/fr/source/conf.py
+++ b/docs/fr/source/conf.py
@@ -11,7 +11,15 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys, os, datetime
+
+
+ISHTAR_PATH = os.path.abspath(
+    os.sep.join(__file__.split(os.sep)[:-1] + ["..", "..", "..", "ishtar_common"]))
+
+sys.path.append(ISHTAR_PATH)
+
+from version import __version__
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -40,17 +48,17 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'Ishtar'
-copyright = u'2018, Ishtar community'
+project = 'Ishtar'
+copyright = '{}, Ishtar community'.format(datetime.date.today().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '2.1'
+version = __version__
 # The full version, including alpha/beta/rc tags.
-release = '2.1-dev-10'
+release = __version__
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/fr/source/index.rst b/docs/fr/source/index.rst
index 54815c98e..73ec3bed5 100644
--- a/docs/fr/source/index.rst
+++ b/docs/fr/source/index.rst
@@ -11,9 +11,12 @@ Contents:
 .. toctree::
    :maxdepth: 3
 
+   installation
    principes
    interface-utilisateur
    interface-administrateur
    annexe-1-rattachement
    annexe-2-permission-action
    annexe-3-ex-flux-ope
+   annexe-tech-1-insee-communes
+   annexe-tech-2-ign-communes
diff --git a/docs/fr/source/installation.rst b/docs/fr/source/installation.rst
index 261284989..68aed6fab 100644
--- a/docs/fr/source/installation.rst
+++ b/docs/fr/source/installation.rst
@@ -5,73 +5,68 @@ Installation
 ============
 
 :Auteur: Étienne Loks
-:Date: 2018-10-02
+:Date: 2020-09-23
 :Copyright: CC-BY 3.0
 
 
-.. warning::
-   Cette documentation concerne la version 1 d'Ishtar. L'installation de la version 2 via paquet n'est pas possible pour l'instant. Un travail est en cours pour que le paquet soit mis à jour d'ici fin 2018. Pour installer la version 2 « à la main », veuillez suivre les instructions sur cette `page`_.
-
-.. _page: https://gitlab.com/iggdrasil/ishtar/blob/develop/INSTALL.md
-
 Ce document présente les instructions d'installation d'Ishtar.
 
 Pour l'instant, elles se limitent à l'installation sous Debian GNU/linux via le paquet Debian.
 
+Un nom de domaine dédié est nécessaire pour chaque instance (une instance Ishtar n'est pas installable dans un sous-répertoire). Par contre un sous-domaine est tout à fait utilisable (par exemple : *ishtar.mon-domaine.net*).
+
 .. note:: Sauf mention explicite, chaque commande est exécutée en tant qu'utilisateur root. Les utilisateurs de sudo l'ajouteront à chaque commande faite.
 
-Installation sur poste Debian Wheezy
+Installation sur poste Debian Buster
 ------------------------------------
 
-Un dépôt a été mis en place pour installer sous Debian Wheezy.
+Un dépôt a été mis en place pour installer sous Debian Buster.
 Ce dépôt est signé, pour ajouter la clé du dépôt à votre gestionnaire de paquet, lancez la commande ::
 
     wget -O - http://deb.iggdrasil.net/contact@iggdrasil.net.gpg.key | apt-key add -
 
 Puis, au choix, ajoutez le dépôt à votre /etc/apt/sources.list ::
 
-    deb http://deb.iggdrasil.net/ wheezy main
-    deb-src http://deb.iggdrasil.net/ wheezy main
+    deb http://deb.iggdrasil.net/apt/debian/ buster main
+    deb-src http://deb.iggdrasil.net/apt/debian/ buster main
 
 Ou sauvegardez le fichier `iggdrasil.list`_ dans votre répertoire **/etc/apt/sources.list.d/** ::
 
-    wget -O - http://deb.iggdrasil.net/dists/wheezy/iggdrasil.list > /etc/apt/sources.list.d/iggdrasil.list
+    wget -O - http://deb.iggdrasil.net/apt/debian/dists/buster/iggdrasil.list > /etc/apt/sources.list.d/iggdrasil.list
 
-.. _iggdrasil.list: http://deb.iggdrasil.net/dists/wheezy/iggdrasil.list
+.. _iggdrasil.list: http://deb.iggdrasil.net/apt/debian/dists/buster/iggdrasil.list
 
 Ensuite mettez à jour la base de données de votre gestionnaire de paquet et installez le paquet ::
 
     apt-get update
-    apt-get install python-django-ishtar
+    apt-get install python3-django-ishtar
 
-Enfin pour créer une nouvelle instance d'Ishtar ::
+Deux paquets optionnels peuvent être installés :
 
-    INSTANCE=le_nom_de_mon_instance URL=ishtar.my-organization.net ishtar-prepare-instance
+* **ishtar-tasks** : installe un service de tâche pour gérer en tâche de fond les opérations longues (par exemple les imports). Cette installation est conseillée si vous n'êtes pas juste en ressources serveur.
+* **ishtar-libreoffice** : installe libreoffice en mode serveur pour faciliter des imports / exports aux formats bureautique. Ce service permettra notamment à terme de gérer les formats Office Open XML de la suite Microsoft Office. Peu utilisé pour le moment, l'installation de ce paquet est tout à fait optionnelle.
 
-INSTANCE est le nom de l'instance et URL le nom du domaine associé (juste l'url pas de http:// ou https://).
 
-.. note:: Le nom de domaine doit bien entendu pointer vers l'adresse IP du serveur. Si à l'issue de l'installation, le service n'est pas joignable, verifiez bien votre configuration DNS ou le cas échéant verifez bien auprès du gestionnaire de nom de domaine que c'est le cas.
+Enfin pour créer une nouvelle instance d'Ishtar ::
 
-D'autres variables sont disponibles :
+    ishtar-prepare-instance
 
-- **UWSGI_PORT** : par défaut à 8891, faites bien attention d'incrémenter ce nombre pour chaque nouvelle instance.
-- **NGINX_PORT** : si vous voulez que le serveur web réponde sur un port différent, par exemple si vous avez déjà Apache installé. Ensuite pour accéder à l'application il faudra mettre clairement le numéro de port dans l'adresse du logiciel. Exemple : http://ishtar.my-organization.net:8000
-- **DB_HOST**, **DB_PORT**, **DB_PASSWORD**, **DB_NAME** : si vous souhaitez personnaliser la base de données dans laquelle sera stockée Ishtar. Par défaut, elle sera stockée localement, sur le port par défaut de PostgreSQL (5432), le mot de passe sera généré aléatoirement, le nom de la base de données sera : « ishtar-le_nom_de_mon_instance ».
+Un ensemble de questions vous sera posé afin de déterminer les paramètres qui concernent cette instance.
 
-.. note:: Pour le nom de l'instance, seuls sont permis le tiret bas **_** et les caractères alphanumériques en minuscule. Ce nom doit commencer par un caractères alphabétique. Évitez aussi des noms pouvant entrer en conflit avec des bibliothèques Python existantes (par exemple « test »).
 
+.. note:: Le nom de domaine doit bien entendu pointer vers l'adresse IP du serveur. Si à l'issue de l'installation, le service n'est pas joignable, verifiez bien votre configuration DNS ou le cas échéant verifez bien auprès du gestionnaire de nom de domaine que c'est le cas.
 
 .. warning::
     En terme de serveur Web, cette première version de l'installateur fonctionne avec la configuration que nous considérons comme la plus optimisée qui est le couple nginx / uwsgi. À terme, l'installateur prendra aussi en compte Apache. Pour l'instant, si vous avez des services tournant sous Apache, plusieurs options se présentent à vous :
  
-    - faire tourner nginx sur un autre port (cf. la variable NGINX_PORT) ;
+    - faire tourner nginx sur un autre port ;
     - faire fonctionner vos autres services avec nginx (je vous laisse découvrir l'abondante documentation en ligne en cherchant « nginx + le nom de mon service ») ;
     - configurer Ishtar pour fonctionner avec Apache (référez vous à la `documentation de Django`_).
 
-.. _`documentation de Django`: https://docs.djangoproject.com/fr/1.9/howto/deployment/wsgi/modwsgi/
+.. _`documentation de Django`: https://docs.djangoproject.com/fr/1.11/howto/deployment/wsgi/modwsgi/
 
 L'installateur vous demandera un identifiant / mot de passe pour le compte administrateur.
-Une fois l'instance préparée une base de données a été crée avec un nom du type ishtar-le_nom_de_mon_instance (ou le nom que vous avez spécifiquement donné), Ishtar est joignable à l'adresse donnée par la variable URL et les données de cette instances sont stockées dans le répertoire /var/lib/python-django-ishtar/le_nom_de_mon_instance.
+Une fois l'instance préparée une base de données a été crée avec un nom du type ishtar-le_nom_de_mon_instance (ou le nom que vous avez spécifiquement donné), Ishtar est joignable à l'adresse donnée par la variable URL et les données de cette instances sont stockées dans le répertoire /srv/ishtar/le_nom_de_mon_instance.
 
 
 Initialisation de la base de données
@@ -107,14 +102,15 @@ Une liste des communes française peut être téléchargée et chargée ::
     wget "http://ishtar-archeo.net/fixtures/initial_towns-fr.tar.bz2"
     tar xvjf initial_towns-fr.tar.bz2
 
-    ISHTAR_PATH=/var/lib/python-django-ishtar # dépend de votre installation
-                                              # ici pour le paquet Debian
+    ISHTAR_PATH=/srv/ishtar # dépend de votre installation
+                            # ici pour le paquet Debian
     PROJECT_PATH=$ISHTAR_PATH/mon_instance
     cd $PROJECT_PATH
     ./manage.py loaddata /tmp/initial_towns-fr.json
     rm /tmp/initial_towns-fr.*
 
-Sinon un script est mis à disposition pour charger des communes depuis des données OSM : $ISHTAR_PATH/scripts/import_towns_from_osm.py
+Sinon un script est mis à disposition pour charger des communes depuis des données OSM : `$ISHTAR_PATH/scripts/import_towns_from_osm.py`.
+
 Lisez les instructions contenu dans le fichier pour savoir comment procéder.
 
 ..
diff --git a/docs/fr/source/interface-administrateur.rst b/docs/fr/source/interface-administrateur.rst
index 651111826..cf8057274 100644
--- a/docs/fr/source/interface-administrateur.rst
+++ b/docs/fr/source/interface-administrateur.rst
@@ -10,6 +10,8 @@ Configuration de l'instance Ishtar
 
 ----------------------------------
 
+.. _interface-administrateur:
+
 La configuration d'Ishtar se fait essentiellement par le biais de « l'interface d'administration ». Cette interface propose une vue brute des tables en base de données. Même si cette interface propose une ergonomie simple et pratique, utiliser cette interface peut nécessiter d'avoir connaissance de notions de base d'une base de données pour pouvoir opérer des choix pertinents.
 
 L'interface d'administration nécessite d'avoir un compte administrateur pour y accéder. Les utilisateurs disposant de ce droit ont une icône « roue dentée » sur la barre de menu à l'extrémité droite. Sauf configuration spécifique, cette interface est aussi disponible via l'adresse « https://monsite-ishtar.net/admin/ » (ajouter `/admin/` à l'adresse de base).
@@ -93,7 +95,7 @@ La création se fait en deux temps, d'abord un paramétrage des champs de base p
 
 Le paramétrage de base demande les champs suivants :
 
-  * **Nom** : le nom correspondant au formulaire personnalisé. Ce nom ne sera visible qu'en administration mais pour s'y retrouver, il doit à la fois reprendre le nom du formulaire ainsi que le contexte pour lequel il a été défini. Par exemple : « Mobilier - 020 - Général - Tout utilisateur » ou « Mobilier - 030 - Conservation - Saisie terrain ».
+* **Nom** : le nom correspondant au formulaire personnalisé. Ce nom ne sera visible qu'en administration mais pour s'y retrouver, il doit à la fois reprendre le nom du formulaire ainsi que le contexte pour lequel il a été défini. Par exemple : « Mobilier - 020 - Général - Tout utilisateur » ou « Mobilier - 030 - Conservation - Saisie terrain ».
 * **Formulaire** : le formulaire à personnaliser. Le nom utilisé permet d'identifier assez simplement le formulaire correspondant car il correspond dans l'ordre (séparé par des tirets) au :
 
   * type d'objet concerné (par exemple : « Mobilier »),
@@ -129,6 +131,8 @@ Les types de profil définiront les types de permissions auxquelles aura accès
 
 Cette interface de création de compte permet aussi de modifier le mot de passe de comptes existants.
 
+.. _permissions-ishtar:
+
 Permissions dans Ishtar
 ***********************
 
@@ -243,9 +247,12 @@ Cela se structure autour des mots clés ``for``, ``in`` et ``endfor``. Au lieu d
 
   Il est possible d'utiliser des images dans les patrons. Pour cela il faut placer une image dans le document du patron et modifier son attribut nom sous LibreOffice (clic droit sur l'image, « Propriétés... » et l'onglet « Options ») par une chaîne sous la forme ``{{ mon_image|image }}``. ``mon_image`` correspond au champ image
 
+.. _configuration-instance-ishtar:
 
+Configuration du profil d'instance Ishtar
+-----------------------------------------
 
-
+*En cours de rédaction...*
 
 .. 
   TODO: Profil d'instance Ishtar