maintenance.init_mathExos

  1# -*- coding: utf-8 -*-
  2"""
  3Ce module code et présente le *manifeste* du dépôt `math-exos`.
  4
  5Modifié le 29/03/23 @author: remy
  6
  7Le manifeste d'un dépôt décrit
  8- les conventions de nommage des fichiers permettant leur traitement local avant publication et contextualisation,
  9- les commandes de traitement local,
 10- les données du serveur de publication spécifique au dépôt,
 11- les données du serveur de contextualisation spécifique au dépôt.
 12
 13
 14Ce module définit un dictionnaire `manifeste`.
 15- `manifeste['nom']` présente le nom du dépôt : 'math-pbs'
 16- `manifeste['execloc']` présente les paramètre de traitement local
 17- `manifeste['espace']` présente les paramètres de publication
 18- `manifeste['context']` présente les paramètres de contextualisation
 19
 20### Conventions de nommage
 21
 22L'élément essentiel de ce dépôt est un exercice. Un exercice particulier est caractérisé par une chaîne (appelé ici assez improprement son titre) formée de 2 lettres puis de 2 chiffres.
 23
 24Les 2 lettres codent un thème d'exercice, les 2 chiffres codent le numéro de l'exercice dans le thème.
 25
 26Le fichier [`_codes.csv`](https://github.com/nicolair/math-exos/blob/master/_codes.csv) dans le dépôt contient la liste des codes avec une
 27brève description. Les premières lignes sont reproduites au dessous :
 28
 29    codetheme;description
 30    al;groupes anneaux corps
 31    am;avec maple
 32    ao;automorphismes orthogonaux
 33    ap;approximations (zéros, intégrales, nombres réels)
 34    ar;arithmétique dans Z et K[X]
 35    ce;(courbes euclidiennes) étude métrique des courbes
 36    cg;Fonctions d’une Variable Géométrique : continuité
 37    co;coniques
 38    cp;nombres complexes
 39
 40Les noms des fichiers LateX caractérisant un exercice sont formés à partir de son titre: précédé par `E` pour l'énoncé et par `C` pour le corrigé. Parfois l'exercice n'est pas encore corrigé et le fichier `C` n'existe pas. Un auteur travaille essentiellement dans ces fichiers `E` et `C`.
 41
 42Exemple `Ecp03.tex` et `Ccp03.tex` pour l'exercice numéro 3 portant sur les
 43nombres complexes.
 44
 45Un fichier Latex dont le nom commence par `Aexo_` suivi du titre d'un exercice présente un exercice (éventuellement corrigé) particulier. De tels fichiers ne devraient pas être édités à la main. Ils sont mis à jour par la maintenance puis compilés dans des fichiers html placés dans *l'espace* de publication.
 46 
 47Un fichier Latex dont le nom commence par `A` suivi du code d'un thème (sans numéro) est la *feuille d'exercice* sur le thème codé qui rassemble tous les exercices du thème. De tels fichiers ne devraient pas être édités à la main.
 48Ils sont mis à jour par la maintenance puis compilés dans des fichiers pdf placés dans *l'espace* de publication.
 49
 50### Traitement local
 51
 52- Avant compilation
 53    - mise à jour des fichiers LateX d'exercices individuels `Aexo_`
 54    - mise à jour des fichiers Latex de feuille par thème `A`
 55    
 56- Avant publication
 57    - les fichiers `Aexo_` sont compilés en html et placés dans `htmldir`
 58    - les fichiers `A` sont compilés en pdf et placés dans `pdfdir`
 59  
 60- Avant contextualisation
 61    - Les fichiers `E` sont scannés pour former les listes par code de thème
 62    - Les fichiers `*.idx` sont scannés pour extraire les index.
 63
 64
 65### Publication
 66
 67Voir le sous-module [`espace`](espace.html) pour la mise en oeuvre de la publication. 
 68
 69Ce sous-module ne définit en clair que les paramètres publics du serveur de publication.
 70Les credentials secrets sont définis dans le fichier local `~/.aws`.
 71
 72
 73### Contextualisation
 74
 75#### Noeuds
 76
 77Les noeuds attachés au dépôt d'exercices sont de plusieurs types. Pour chaque type, on indique un exemple de requête cypher renvoyant un unique noeud.
 78
 79- Noeud (`Document`) associé à un exercice particulier caractérisé par son titre
 80    
 81        MATCH (e:Document {typeDoc:"exercice", discipline:"mathématique", titre:"dt23"}) RETURN e
 82
 83- Noeud (`Document`) associé à une feuille d'exercices caractérisée par son titre
 84    
 85        MATCH (f:Document {typeDoc:"liste exercices", titre:"Déterminants"}) RETURN f
 86
 87- Noeud (`Concept`) associé à un thème d'exercices caractérisé par son littéral
 88    
 89        MATCH (c:Concept {typeConcept:"thème feuille exercices", :"Déterminants"}) RETURN c
 90
 91Le titre du document "feuille" est égal au littéral du concept "thème" associé au même thème d'exercices.
 92#### Arêtes
 93
 94- Arête (`CONTIENT`) entre une feuille et un exercice
 95- Arête (`EVALUE`) entre un exercice et le concept de son thème
 96- Arête (`EVALUE`) entre une feuille et le concept de son thème
 97- Arête (`INDEXE`) entre un exercice et un concept dont le littéral est indéxé
 98 "en dur" dans le fichier source Latex de l'exercice.
 99
100Le titre du document "feuille" et le littéral du concept évalué attaché à la même ligne du fichier `_code.csv` doivent être égaux.
101
102On peut insérer directement dans la base des relations qui ne viennent pas des fichiers du dépot. Par exemple des relations `EVALUE` entre un concept (autre qu'un thème d'exercice) et un exercice spécifique.
103
104Voir les sous modules [`graphdb`](graphdb.html), [`bdg_mathExos`](bdg_mathExos.html) pour la mise en oeuvre de la contextualisation.
105
106Ce sous-module ne définit en clair que les paramètres publics du serveur de contextualisation.
107Les credentials secrets sont définis dans les variables d'environnement `NEO4J_URL` et `NEO4J_PASSWORD`.
108
109### Scénarios de travail admissibles
110- supprimer un exercice
111- créer un exercice dans une feuille existante
112- ajouter un corrigé
113- modifier un énoncé ou un corrigé
114- ajouter un index en insérant à la main
115    - les commandes `index{}` dans le fichier `E`
116    - la commande `\makeindex` dans le préambile du fichier `Aexo`
117
118"""
119import os
120
121# nouvelle organisation
122
123execloc = {
124    'relative_path': '../math-exos/',
125    'modulespec': 'exl_mathExos',
126    'commandes': [
127        {'ext': '.tex',
128         'patterns': ['A_*.tex'],
129         'imgdir': 'pdfdir/',
130         'imgext': '.pdf',
131         'command': [
132             "latexmk",
133             "-pdf",
134             "-emulate-aux-dir",
135             "-auxdir=auxdir",
136             "-outdir=pdfdir"
137             ]
138         },
139         {'ext': '.asy',
140          'patterns': ['*_fig.asy'],
141          'imgdir': '',
142          'imgext': '.pdf',
143          'command': [
144              "asy",
145              "-f",
146              "pdf"
147              ]
148          },
149          {'ext': '.py',
150           'patterns': ['*_fig.py'],
151           'imgdir': '',
152           'imgext': '.pdf',
153           'command': [
154               "python3"
155               ]
156           },
157          {'ext': '.tex',
158           'patterns': ['Aexo_*.tex'],
159           'imgdir': 'htmldir/',
160           'imgext': '.html',
161           'command': [
162               'make4ht',
163               '-u',
164               '-d',
165               'htmldir'
166               ]
167           }
168        ],
169    'publish_data': {
170        'patterns': ['pdfdir/A_*.pdf', 'htmldir/*']
171        },
172    'context_data': {
173        'idx_path_pattern': 'Aexo_*.idx'
174        }
175    }
176
177espace = {
178    'credentials': {
179        'region_name': 'fra1',
180        'endpoint_url': 'https://fra1.digitaloceanspaces.com',
181        'bucket': 'maquisdoc-math',
182        'prefix': 'math-exos/',
183                   },
184        'uri_esp': 'https://maquisdoc-math.fra1.digitaloceanspaces.com/'
185    }
186
187context = {
188    'credentials': {
189        'URI': os.getenv('NEO4J_URL'),
190        'user': os.getenv('NEO4J_USERNAME'),
191        'password': os.getenv('NEO4J_PASSWORD')
192        },
193    'modulespec': 'bdg_mathExos'
194    }
195
196manifeste = {'nom': 'math-exos',
197             'execloc': execloc,
198             'espace': espace,
199             'context': context}