Docs: autogen value documentation

3 files changed, 398 insertions, 0 deletions

diff --git a/docs/fr/source/_templates/annexe-tech-3-variables-gen.jinja b/docs/fr/source/_templates/annexe-tech-3-variables-gen.jinja
new file mode 100644
index 000000000..e9576352e
--- /dev/null
+++ b/docs/fr/source/_templates/annexe-tech-3-variables-gen.jinja
@@ -0,0 +1,79 @@
+.. -*- coding: utf-8 -*-
+
+.. _annexe-technique-3-variables:
+
+==============================
+Annexe technique 3 - Variables
+==============================
+
+:Auteur: Étienne Loks
+:Date: 2020-11-24
+:Copyright: CC-BY 3.0
+
+----------------------------------
+
+Ces variables sont utilisées pour les configurations des imports, les patrons de documents et la configuration des identifiants, des index personnalisés.
+
+Ces variables correspondent aux noms des champs utilisés en base de données (exemple : ``code_patriarche`` pour accéder au code patriarche d'une opération) ainsi que des « facilitateurs » qui permettent de disposer de champs plus évolués (exemple : ``get_next_index`` pour accéder au prochain numéro d'index).
+
+On peut passer d'un élément lié à un autre (par exemple, accéder à l'opération d'une unité d'enregistrement) avec la notation double tiret `__` et ensuite accéder aux variables de l'élément lié (exemple : ``operation__code_patriarche`` permet d'accéder au code patriarche de l'opération ).
+
+Ci-dessous la liste des variables pour chaque type d'éléments.
+
+.. _valeurs-champs-adresse:
+
+Champs adresse
+==============
+
+Les champs adresse sont une liste de variables partagées par plusieurs éléments :
+{{ ishtar_common['address']['render'] }}
+
+.. _valeurs-champs-geo:
+
+Champs géographiques
+====================
+
+Les champs géographiques sont une liste de variables partagées par plusieurs éléments :
+{{ ishtar_common['geoitem']['render'] }}
+
+Le détail du fonctionnement de ces champs est explicité dans :ref:`« Principes > Notions avancées > Données géographiques » <donnees-geographiques>`.
+
+
+Personne
+========
+
+Chaque personne dispose des :ref:`champs adresse <valeurs-champs-adresse>`, ainsi que des champs suivants :
+{{ ishtar_common['person']['render'] }}
+
+
+Auteur
+======
+{{ ishtar_common['author']['render'] }}
+
+Organisation
+============
+
+Chaque organisation dispose des :ref:`champs adresse <valeurs-champs-adresse>`, ainsi que des champs suivants :
+{{ ishtar_common['organization']['render'] }}
+
+
+Documentation
+=============
+
+{{ ishtar_common['document']['render'] }}
+
+Opération
+=========
+
+Chaque opération dispose des :ref:`champs géographiques <valeurs-champs-geo>`, ainsi que des champs suivants :
+
+
+Site/Entité archéologique
+=========================
+
+Chaque opération dispose des :ref:`champs géographiques <valeurs-champs-geo>`, ainsi que des champs suivants :
+
+
+Dossier archéologique
+=====================
+
diff --git a/docs/fr/source/annexe-tech-3-variables-gen.rst b/docs/fr/source/annexe-tech-3-variables-gen.rst
new file mode 100644
index 000000000..747e33ad8
--- /dev/null
+++ b/docs/fr/source/annexe-tech-3-variables-gen.rst
@@ -0,0 +1,233 @@
+.. -*- coding: utf-8 -*-
+
+.. _annexe-technique-3-variables:
+
+==============================
+Annexe technique 3 - Variables
+==============================
+
+:Auteur: Étienne Loks
+:Date: 2020-11-24
+:Copyright: CC-BY 3.0
+
+----------------------------------
+
+Ces variables sont utilisées pour les configurations des imports, les patrons de documents et la configuration des identifiants, des index personnalisés.
+
+Ces variables correspondent aux noms des champs utilisés en base de données (exemple : ``code_patriarche`` pour accéder au code patriarche d'une opération) ainsi que des « facilitateurs » qui permettent de disposer de champs plus évolués (exemple : ``get_next_index`` pour accéder au prochain numéro d'index).
+
+On peut passer d'un élément lié à un autre (par exemple, accéder à l'opération d'une unité d'enregistrement) avec la notation double tiret `__` et ensuite accéder aux variables de l'élément lié (exemple : ``operation__code_patriarche`` permet d'accéder au code patriarche de l'opération ).
+
+Ci-dessous la liste des variables pour chaque type d'éléments.
+
+.. _valeurs-champs-adresse:
+
+Champs adresse
+==============
+
+Les champs adresse sont une liste de variables partagées par plusieurs éléments :
+
+- `address` : Adresse
+- `address_complement` : Complément d'adresse
+- `alt_address` : Autre adresse : adresse
+- `alt_address_complement` : Autre adresse : complément d'adresse
+- `alt_address_is_prefered` : L'adresse alternative est préférée
+- `alt_country` : Autre adresse : pays
+- `alt_postal_code` : Autre adresse : code postal
+- `alt_town` : Autre adresse : ville
+- `country` : Pays
+- `email` : Courriel
+- `mobile_phone` : Téléphone mobile
+- `need_update` : Nécessite une mise à jour
+- `phone` : Téléphone
+- `phone2` : Type de téléphone 2
+- `phone3` : Téléphone 3
+- `phone_desc` : Type de téléphone
+- `phone_desc2` : Type de téléphone 2
+- `phone_desc3` : Type de téléphone 3
+- `postal_code` : Code postal
+- `precise_town` : -> Commune
+- `raw_phone` : Téléphone brut
+- `town` : Commune (saisie libre)
+
+.. _valeurs-champs-geo:
+
+Champs géographiques
+====================
+
+Les champs géographiques sont une liste de variables partagées par plusieurs éléments :
+
+- `estimated_error_x` : Erreur estimée pour X
+- `estimated_error_y` : Erreur estimée pour Y
+- `estimated_error_z` : Erreur estimée pour Z
+- `multi_polygon` : Polygones multi-parties
+- `multi_polygon_source` : Source du multi-polygone
+- `multi_polygon_source_item` : Élément source du multi-polygone
+- `point` : Point
+- `point_2d` : Point (2D)
+- `point_source` : Source du point
+- `point_source_item` : Élément source du point
+- `spatial_reference_system` : -> Système de référence spatiale
+- `x` : X/Long
+- `y` : Y/Lat
+- `z` : Z
+
+Le détail du fonctionnement de ces champs est explicité dans :ref:`« Principes > Notions avancées > Données géographiques » <donnees-geographiques>`.
+
+
+Personne
+========
+
+Chaque personne dispose des :ref:`champs adresse <valeurs-champs-adresse>`, ainsi que des champs suivants :
+
+- `adminact_operation_in_charge` : -> Acte administratif
+- `adminact_scientist` : -> Acte administratif
+- `archived` : archived
+- `attached_to` : -> Organisation
+- `author` : -> Auteur
+- `cached_label` : Nom en cache
+- `cira_rapporteur` : -> Opération
+- `comment` : Commentaire
+- `contact_type` : Type de contact
+- `file_responsability` : -> Dossier archéologique
+- `general_contractor_files` : -> Dossier archéologique
+- `ishtaruser` : -> Utilisateur d'Ishtar
+- `manage_treatments` : -> Traitement
+- `merge_candidate` : -> Personne
+- `merge_exclusion` : -> Personne
+- `merge_key` : Clé de fusion
+- `minutes_writer` : -> Opération
+- `name` : Nom
+- `old_title` : Titre
+- `operation_collaborator` : -> Opération
+- `operation_protagonist` : -> Opération
+- `operation_responsability` : -> Opération
+- `operation_scientist_responsability` : -> Opération
+- `parcel_owner` : -> Propriétaire de parcelle
+- `person_types` : -> Type de personne
+- `profiles` : -> Profil d'utilisateur
+- `properties` : -> Propriété
+- `raw_name` : Nom brut
+- `responsible_town_planning_service_files` : -> Dossier archéologique
+- `salutation` : Formule d'appel
+- `scientist` : -> Dossier archéologique
+- `signatory` : -> Acte administratif
+- `site_collaborator` : -> Entité archéologique
+- `surname` : Prénom
+- `title` : -> Type de titre
+- `treatmentfile_applicant` : -> Demande de traitement
+- `treatmentfile_responsability` : -> Demande de traitement
+- `treatments` : -> Traitement
+- `warehouse_in_charge` : -> Lieu de conservation
+
+
+Auteur
+======
+
+- `author_type` : -> Type d'auteur
+- `cached_label` : Nom en cache
+- `documents` : -> Document
+- `person` : -> Personne
+
+Organisation
+============
+
+Chaque organisation dispose des :ref:`champs adresse <valeurs-champs-adresse>`, ainsi que des champs suivants :
+
+- `adminact_operator` : -> Acte administratif
+- `archived` : archived
+- `cached_label` : Nom en cache
+- `files` : -> Dossier archéologique
+- `general_contractor_files` : -> Dossier archéologique
+- `members` : -> Personne
+- `merge_candidate` : -> Organisation
+- `merge_exclusion` : -> Organisation
+- `merge_key` : Clé de fusion
+- `name` : Nom
+- `operation_applicant_authority` : -> Opération
+- `operator` : -> Opération
+- `organization_type` : -> Type d'organisation
+- `planning_service_files` : -> Dossier archéologique
+- `publish` : -> Document
+- `treatmentfile_applicant` : -> Demande de traitement
+- `treatments` : -> Traitement
+- `url` : Adresse web
+- `warehouses` : -> Lieu de conservation
+
+
+Documentation
+=============
+
+
+- `additional_information` : Information supplémentaire
+- `associated_file` : associated file
+- `associated_links` : Liens symboliques
+- `associated_url` : Ressource numérique (adresse web)
+- `authors` : -> Auteur
+- `authors_raw` : Auteurs (brut)
+- `cache_related_label` : Lié
+- `children` : -> Document
+- `comment` : Commentaire
+- `complete_identifier` : Complete identifier
+- `container_id` : Container ID
+- `container_ref_id` : Container ID
+- `containers` : -> Contenant
+- `context_records` : -> Unité d'Enregistrement
+- `creation_date` : Date de création
+- `custom_index` : Custom index
+- `description` : Description
+- `duplicate` : Existe en doublon
+- `external_id` : Identifiant
+- `files` : -> Dossier archéologique
+- `finds` : -> Mobilier
+- `format_type` : -> Type de format
+- `image` : image
+- `index` : Index
+- `internal_reference` : Réf. interne
+- `isbn` : ISBN
+- `issn` : ISSN
+- `item_number` : Nombre d'éléments
+- `language` : -> Langue
+- `licenses` : -> Type de licence
+- `main_image_containers` : -> Contenant
+- `main_image_context_records` : -> Unité d'Enregistrement
+- `main_image_finds` : -> Mobilier
+- `main_image_operations` : -> Opération
+- `main_image_sites` : -> Entité archéologique
+- `main_image_treatment_files` : -> Demande de traitement
+- `main_image_treatments` : -> Traitement
+- `main_image_warehouses` : -> Lieu de conservation
+- `operations` : -> Opération
+- `publisher` : -> Organisation
+- `qrcode` : qrcode
+- `receipt_date` : Date de réception
+- `receipt_date_in_documentation` : Date de réception en documentation
+- `reference` : Réf.
+- `scale` : Échelle
+- `sites` : -> Entité archéologique
+- `source` : -> Document
+- `source_free_input` : Source - free input
+- `source_page_range` : Source - page range
+- `source_type` : -> Document type
+- `support_type` : -> Type de support
+- `tags` : -> Document tag
+- `thumbnail` : thumbnail
+- `title` : Titre
+- `treatment_files` : -> Demande de traitement
+- `treatments` : -> Traitement
+- `warehouses` : -> Lieu de conservation
+
+Opération
+=========
+
+Chaque opération dispose des :ref:`champs géographiques <valeurs-champs-geo>`, ainsi que des champs suivants :
+
+
+Site/Entité archéologique
+=========================
+
+Chaque opération dispose des :ref:`champs géographiques <valeurs-champs-geo>`, ainsi que des champs suivants :
+
+
+Dossier archéologique
+=====================
diff --git a/docs/generate_values_doc.py b/docs/generate_values_doc.py
new file mode 100644
index 000000000..ce1406663
--- /dev/null
+++ b/docs/generate_values_doc.py
@@ -0,0 +1,86 @@
+from django.apps import apps
+from django.conf import settings
+from django.utils.translation import activate
+
+from jinja2 import Template
+import os
+
+
+from ishtar_common.models_common import Address, GeoItem
+
+TEMPLATES = (
+    ("fr/source/_templates/annexe-tech-3-variables-gen.jinja",
+     "fr/source/annexe-tech-3-variables-gen.rst",
+     "fr-fr"),
+)
+
+TPL_MODEL = {
+    "fr-fr": """{% for field_name, desc in fields %}
+- `{{field_name}}` : {{desc}}{% endfor %}"""
+}
+
+EXCLUDED = ["id", "data", "history_creator", "history_m2m", "history_modifier",
+            "imports", "last_modified", "lock_user", "locked", "search_vector",
+            "uuid"]
+EXCLUDED_MODELS = {}
+ONLY_MODELS = {
+    "ishtar_common": ["person", "organization", "author", "document"]
+}
+
+APP_LIST = ["ishtar_common"]
+
+
+def get_values(tpl_model, model, excluded):
+    fields = {}
+    related_fields = {}
+    for field in model._meta.get_fields():
+        if field.name in excluded:
+            continue
+        if getattr(field, "related_model", None):
+            related_fields[field.name] = \
+                "-> " + str(field.related_model._meta.verbose_name)
+        elif hasattr(field, "verbose_name"):
+            fields[field.name] = str(field.verbose_name)
+    fields = sorted(list(fields.items()) + list(related_fields.items()))
+    dct = {
+        "fields": [k for k, __ in fields],
+        "render": tpl_model.render({"fields": fields})
+    }
+    return dct
+
+
+for template_name, template_name_dest, language in TEMPLATES:
+    tpl_model = Template(TPL_MODEL[language])
+    activate(language)
+    render_dct = {'ishtar_common': {}}
+    excluded = EXCLUDED[:]
+
+    address_values = get_values(tpl_model, Address, excluded=excluded)
+    render_dct["ishtar_common"]["address"] = address_values
+    excluded += address_values["fields"]
+
+    geo_values = get_values(tpl_model, GeoItem, excluded=excluded)
+    render_dct["ishtar_common"]["geoitem"] = geo_values
+    excluded += geo_values["fields"]
+
+    for app_name in APP_LIST:
+        app_models = apps.get_app_config(app_name).get_models()
+        for model in list(app_models):
+            model_name = model._meta.model_name
+            if app_name in EXCLUDED_MODELS and \
+                    model_name in EXCLUDED_MODELS[app_name]:
+                continue
+            if app_name in ONLY_MODELS and \
+                    model_name not in ONLY_MODELS[app_name]:
+                continue
+            render_dct[app_name][model._meta.model_name] = get_values(
+                tpl_model, model, excluded)
+
+    template_name = os.path.abspath(
+        settings.ROOT_PATH + "../docs/" + template_name)
+    template_name_dest = os.path.abspath(
+        settings.ROOT_PATH + "../docs/" + template_name_dest)
+    with open(template_name, "r") as tpl:
+        rendered = Template(tpl.read())
+        with open(template_name_dest, "w") as tpl_dest:
+            tpl_dest.write(rendered.render(render_dct))