diff -r b7d19cd87fcf -r 09e00f38d177 src/hdalab/views/ajax.py
--- a/src/hdalab/views/ajax.py	Thu Apr 12 01:27:16 2018 +0200
+++ b/src/hdalab/views/ajax.py	Wed Apr 11 12:19:47 2018 +0200
@@ -23,6 +23,23 @@
 logger = logging.getLogger(__name__)
 
 def tagtranslation(request):
+    """
+    Vue donnant des traductions de label de tag pour une langue.
+    la recherche se fait dans les objets :class:`hdalab.models.DbpediaFieldsTranslation`.
+
+    Paramêtres GET:
+        :var lang: La langue demandée
+        :var labels: Un ou plusieurs labels de tag (séparateur : ",")
+
+    Réponse (application/json):
+        Un dictionnaire sous la forme ::
+
+            {
+                "<label1>": "<translation>",
+                "<label2>": "<translation>"
+            }
+
+    """
 
     lang = request.GET.get('lang',request.LANGUAGE_CODE)
     labels = request.GET.get('labels',None)
@@ -46,7 +63,19 @@
 
     return HttpResponse(content=json.dumps(translations), content_type='application/json')
 
-def subcat(category, globtags, level, max_level ):
+
+
+def subcat(category, globtags, level, max_level):
+    """
+    Méthode récursive utilisée pour reconstruire un arbre de catégories.
+
+    :param object category: La catégorie racine.
+    :param dict globtags: dictionnaire flobal des tags.
+    :param int level: Niveau de récursion.
+    :param int max_level: Niveau maximum de récursion (level <= max_level)
+
+    :returns: L'arbre des catégories.
+    """
     # recursive function used by cattree
     catlabel = category.label
     tags = Tag.objects.filter(wp_categories__wp_category = category).distinct()
@@ -70,6 +99,15 @@
     return resobj
 
 def cleantags(category):
+    """
+    Methode annexe qui nettoie recursivement un arbre de catégorie. elle effectue les actions suivantes:
+      - retire les clefs correspondant à des listes vides ('contents' et 'themes')
+      - trie les listes 'themes' par label
+      - trie les listes 'contents' par score
+
+    :param category: la catégorie racine où commencer le traitement.
+
+    """
     if category.has_key('contents') and len(category['contents']) == 0:
         del category['contents']
     if category.has_key('contents'):
@@ -86,6 +124,37 @@
     return category
 
 def cattree(request):
+    """
+    Contruit l'arbre de catégorie pour un label.
+    Les contenus attachés aux noeud sont des listes de fiches hdalab triées par score.
+    Le score pour une fiche est fonction de ses tags, de leur ordre, de leur présence dnas l'arbre des catégories et de leur hauteur dans l'arbre des catégories.
+
+    Paramêtres GET :
+        :var label: Le label
+
+    Réponse (application/json):
+        Un json représentant l'arbre des catégories avec pour chaque noeud une liste ordonnée de fiches liée à la catégorie.
+
+        exemple ::
+
+            {
+                "label": "<label1>",
+                "themes": [ { "label": "<label1.1>", "themes": [...], "contents": [...]}, ...],
+                "contents": [
+                    {
+                        "organization": "Ciclic",
+                        "description": "Ciclic propose...",
+                        "score": 7,
+                        "title": "Vocabulaire de l'analyse filmique...",
+                        "url": "http://upopi.ciclic.fr/vocabulaire/definition/sceance-11",
+                        "hda_id": "5879",
+                        "organization_url": "http://www.ciclic.fr/",
+                        "id": 14852
+                    },
+                    ...
+                ]
+            }
+    """
     # Gets the category tree from a label
     ROOT_MAX_TAG_ORDER = 8
     MAX_TAG_ORDER = 8
@@ -146,7 +215,12 @@
 
     return HttpResponse(content=json.dumps(resobj), content_type='application/json')
 
+
 def sessioninfo(request):
+    """
+    Vue gérant les session Hda permettant de sauvegarder un état d'interface.
+    Note : Cette vue n'est pas mappée dans le module `hdalab.url`.
+    """
 
     data = json.loads(request.GET.get('data', "{}"))
     write = False
@@ -188,6 +262,41 @@
 
 
 def tagsearch(request):
+    """
+    Vue permettant la recherche dans les tag.
+    La recherche se fait dans les objets :class:`hdabo.models.Tag`, :class:`hdalab.models.DbpediaFields` et :class:`hdalab.models.DbpediaFieldsTranslation`.
+
+    Paramêtres GET:
+        :var (str) term: Le terme à rechercher.
+        :var (str) lang: La langue dans laquelle il faut faire la recherche.
+        :var (int) count: Le nombre maximum de résultat.
+        :var (bool) count_notices: Ajoute ou pas le nombre de notices par tag.
+
+    Réponse (application/json):
+        Une liste comprenant les résultats de la recherche.
+
+        exemple ::
+
+            [
+                {
+                    "original_label": "Cathédrale Notre-Dame de Chartres",
+                    "url": "http://fr.wikipedia.org/wiki/Cath%C3%A9drale_Notre-Dame_de_Chartres",
+                    "abstract": "La cathédrale Notre-Dame de Chartres ...",
+                    "value": "Cathédrale Notre-Dame de Chartres",
+                    "thumbnail": "http://commons.wikimedia.org/wiki/Special:FilePath/Chartres_Cath+Gare.JPG?width=300",
+                    "nb": 7
+                },
+                {
+                    "original_label": "Cathédrale Notre-Dame de Paris",
+                    "url": "http://fr.wikipedia.org/wiki/Cath%C3%A9drale_Notre-Dame_de_Paris",
+                    "abstract": "La cathédrale Notre-Dame de Paris...",
+                    "value": "Cathédrale Notre-Dame de Paris",
+                    "thumbnail": "http://commons.wikimedia.org/wiki/Special:FilePath/Notre_Dame_de_Paris_DSC_0846w.jpg?width=300",
+                    "nb": 6
+                },
+                ...
+            ]
+    """
 
     q = request.GET.get('term',None)
     maxcount = int(request.GET.get('count','40'))
@@ -252,7 +361,29 @@
 
     return HttpResponse(content=json.dumps(res), content_type='application/json')
 
+
+
 def catsearch(request):
+    """
+    Vue permettant la recherche de catégorie. On se restreint aux catégories qui sont aussi des tags.
+
+    Paramêtres GET:
+        :var (str) term: Le terme à rechercher.
+
+    Réponse (application/json):
+        Une liste comprenant le résultat de la recherche.
+
+        exemple ::
+
+            [
+                { "value": "1982 au cinéma" },
+                { "value": "Cinéma italien" },
+                { "value": "2003 au cinéma" },
+                ...
+            ]
+
+    """
+
 
     q = request.GET.get('term',None)
 
@@ -268,7 +399,27 @@
 
     return HttpResponse(content=json.dumps(res), content_type='application/json')
 
+
+
 def filter(request):
+    """
+    Vue permettant de filtrer par facette des fiches HDA.
+    Cette méthode est en fait un simple wrapper pour la méthode `filter_generic`.
+
+    Paramêtres GET:
+        :var lang: la langue de recherche (défaut: fr-fr).
+        :var period: Période dans laquelle doit se faire la recherche.
+        :var label: un mot-clef.
+        :var country: Une liste de pays limitant la recherche.
+        :var contentlist: Liste de fiches limitant la recherche.
+        :var mto: Ordre maximum des tags (défaut: 12).
+        :var contentcount: nombre de fiches maximum (défaut : 8).
+        :var tagcount: nombre maximum de tag (défaut: 30).
+
+    Réponse (application/json):
+        Un objet comprenant le résultat de la recherche.
+    """
+
 
     lang = request.GET.get('lang',request.LANGUAGE_CODE)
     periode = request.GET.get('period',None)
@@ -285,6 +436,128 @@
 
 
 def filter_generic(lang="fr-fr", periode=None, label=None, country=None, contentlist=None, max_tag_order=12, content_count=8, tag_count=30):
+    """
+    Méthode de recherche par facette sur les fiches HDA.
+
+    :param str lang: La langue de recherche (défaut: "fr-fr").
+    :param str period: Période d'année limitant la recherche. Le format est `<année-début>,<année-fin>` (défaut: None).
+    :param str label: Limite la recherche à un label de tag (défaut: None).
+    :param str country: Liste de pays où limiter la recherche. Le format est `<uri dbpedia pays 1>,<uri dbpedia pays 2>...` (défaut: None).
+    :param str contentlist: Liste d'id de fiche HDA (:class:`hdabo.models.Datasheet`) limitant la recherche. Le format est `<id1>,<id2>...` (défaut: None)
+    :param int max_tag_order: Limite le nombre maximum de tag par fiche (défaut: 12).
+    :param int content_count: Limite le nombre de fiches résultat (défaut: 8).
+    :param int tag_count: Limite le nombre de tag dans le résultat (défaut: 30).
+    :rtype: string
+    :returns: Un objet json sérialisé comprenant les résultats de la recherche pour les différentes facettes.
+
+
+    Clefs de l'objet:
+        - :count: Nombre total de fiches.
+        - :disciplines: Liste de disciplines artistiques en relation avec les reesultats, triée par score.
+        - :countries: Objet dont les clef sont des uri dbpedia de pays et les valeurs sont le nombre de fiches.
+        - :tags: Liste de tag triés par score.
+        - :sparkline: Liste d'année avec un score, triés par année. Le score est lié au nombre de fiche dont le contenu couvre l'année en question.
+        - :contents: Liste de fiches HDA répondant à la recherche, classée par score. Chaque fiche comporte une liste de tag.
+        - :tagtranslations: Objet donnant les traductions de label de tag rencontrés dans les résultats.
+
+    exemple::
+
+        {
+            "count": 936,
+            "disciplines": [
+                {
+                "translated_label": "Peinture",
+                "score": 936,
+                "label": "Peinture"
+                },
+                {
+                "translated_label": "Sculpture",
+                "score": 88,
+                "label": "Sculpture"
+                },
+                ...
+            ],
+            "countries": {
+                "http://fr.dbpedia.org/resource/Iran": 1,
+                "http://fr.dbpedia.org/resource/Espagne": 16,
+                ...
+            },
+            "tags": [
+                {
+                "url": "http://fr.dbpedia.org/resource/Portrait",
+                "id": 63452,
+                "translated_label": "Portrait",
+                "score": 179,
+                "wkpd_url": "http://fr.wikipedia.org/wiki/Portrait",
+                "label": "Portrait",
+                "thumbnail": "http://commons.wikimedia.org/wiki/Special:FilePath/Fayum02.jpg?width=300"
+                },
+                ...
+            ],
+            "sparkline": [
+                {
+                "score": 2,
+                "year": -600
+                },
+                {
+                "score": 4,
+                "year": -500
+                },
+                ...
+                {
+                "score": 18,
+                "year": 2001
+                }
+            ],
+            "contents": [
+                {
+                "description": "Le palais Fesch, ...",
+                "title": "Histoires bibliques",
+                "url": "http://www.musee-fesch.com/index.php/musee_fesch/content/view/ef_catalogue_sommaire/1513/%28node_id_theme%29/33459",
+                "tags": [
+                    {
+                    "url": "http://fr.dbpedia.org/resource/Peinture",
+                    "id": 54648,
+                    "translated_label": "Peinture",
+                    "wkpd_url": "http://fr.wikipedia.org/wiki/Peinture",
+                    "label": "Peinture",
+                    "order": 1,
+                    "match": true
+                    },
+                    ...
+                ],
+                "score": 23,
+                "coords": {
+                    "city_name": "Ajaccio",
+                    "latitude": 41.916667,
+                    "longitude": 8.733333
+                },
+                "hda_id": "4448",
+                "id": 13855
+                },
+                {
+                "description": "...",
+                "title": "Le XIXe siècle",
+                "url": "http://www.grandpalais.fr/fr/article/le-xixe-siecle",
+                "tags": [ ... ],
+                "score": 22,
+                "hda_id": "5217",
+                "id": 13582
+                },
+                ...
+            ],
+            "tagtranslations": {
+                "Paul Cézanne": "Paul Cézanne",
+                "Politique": "Politique",
+                "Poésie": "Poésie",
+                "Religion": "Religion",
+                "Empereur": "Empereur",
+                "Saint": "Saint",
+                ...
+            }
+        }
+
+    """
 
     no_translate_langs = [ 'fr' ]
 
@@ -474,6 +747,66 @@
 
 
 def subtree(tree):
+    """
+    Methode récursive permettant de remplir un arbre ce catégories avec les fiches HDA correspondantes.
+
+    :param tree: L'arbre de catégorie
+
+    :returns:Un arbre de catégorie rempli de fiches HDA.
+
+    format du paramêtre `tree` ::
+
+        {
+            "label": "secteur urbain",
+            "contents": [
+                { "label": "banlieue",
+                    "contents": [
+                        { "label": "faubourg" }
+                    ] },
+                { "label": "îlot" },
+                ...
+            ]
+        }
+
+    Exemple de retour ::
+
+
+        {
+            "label": "secteur urbain",
+            "contents": [
+                {
+                    "score": 6,
+                    "organization": "Institut national de l'audiovisuel ( INA )",
+                    "description": "Pour faire face à la ...",
+                    "title": "La construction des grands ensembles de banlieue : l'exemple de Sarcelles",
+                    "url": "http://fresques.ina.fr/jalons/fiche-media/InaEdu01075/la-construction-des-grands-ensembles-de-banlieue--l-exemple-de-sarcelles",
+                    "hda_id": "2090",
+                    "organization_url": "http://www.ina.fr",
+                    "id": 12360
+                },
+                {
+                    "score": 6,
+                    "organization": "Maison de banlieue et d'architecture",
+                    "description": "La Maison de banlieue et d'architecture...",
+                    "title": "Des ensembles assez grands. Mémoire et projets en Essonne",
+                    "url": "http://maisondebanlieue.fr/wp-content/uploads/2011/05/Cahier11_grands_ensembles.pdf",
+                    "hda_id": "5893",
+                    "organization_url": "http://www.maisondebanlieue.fr/",
+                    "id": 14821
+                },
+                ...
+            ]
+            "themes": [
+                {
+                    "label": "faubourg",
+                    "content":  [...],
+                    "themes": [...]
+                },
+                ...
+            ]
+        }
+
+    """
     MAX_TAG_ORDER = 16
     label = tree['label']
     sub = tree.get('contents',[])
@@ -497,6 +830,31 @@
     return res
 
 def filltree(request):
+    """
+    Vue permettant d'ajouter des fiches à un arbre de catégories.
+    Cette méthode est en fait un simple wrapper pour la méthode :meth:`subtree`.
+
+    Paramêtres GET:
+        :var tree: Serialisation json d'un arbre de catégories à remplir. exemple:
+
+        ::
+
+            {
+                "label": "secteur urbain",
+                "contents": [
+                    { "label": "banlieue",
+                      "contents": [
+                          { "label": "faubourg" }
+                      ] },
+                    { "label": "îlot" },
+                    ...
+                ]
+            }
+
+    Réponse (application/json):
+        L'arbre de catégories remplis de fiches HDA (c.f. retour methode :meth:`subtree`)
+
+    """
 
     tree = request.GET.get('tree','{}')