diff --git a/docs/AdminUsers.md b/docs/AdminUsers.md index ebc727b26..a639c9fa8 100644 --- a/docs/AdminUsers.md +++ b/docs/AdminUsers.md @@ -3,32 +3,217 @@ ScoDoc gère sa liste d'utilisateurs (enseignants, secrétaires) dans une base de données SQL. +### Principes généraux -/!\ Il est prévu de développer un connecteur vers LDAP, mais ce n'est pas encore disponible (avis aux volontaires, voir https://www-lipn.univ-paris13.fr/projects/scodoc/ticket/140) +Depuis ScoDoc 9.0, la liste des utilisateurs est enregistrée dans la base de +données unique SCODOC (en production) (voir la partie implémentation pour plus +de détails). + +Les entités gérées par scodoc sont : +- Les utilisateurs ; +- les rôles ; +- en liaison avec les départements. + +#### L'entité utilisateur +- possède les propriétés habituelles (nom, prénom, user_name, email); +- peut être associé à un département ou pas (cas d'un administrateur gérant + plusieurs départements); +- assure un ou plusieurs rôles. + +#### L'entité rôle +Un rôle est le regroupement d'un certain nombre de privilèges. +C'est généralement la combinaison d'un département et d'un type d'utilisation. +Actuellement au nombre de quatre (d'autres sont prévus, notamment pour le module +relations entreprises) : +- Administrateur +- Secrétariat +- Enseignant +- Observateur + +par ailleurs, le contexte d'utilisation donne certains privilèges (par exemple +la faculté de saisir des notes, de justifier des absences, de modifier la +définition des programmes, ...). + +_Exemple:_ + +L'utilisateur 'Dupont' est responsable ScoDoc pour son département *RT* mais +intervient également en enseignement au département *GEII*. +On pourra lui attribuer les rôles `AdminRT` et `EnsGEII`, ce qui lui permettra : + +- de gérer les utilisateurs du (seul) département RT : +Privilèges associés : `Gérer les utlisateurs (Sco Users Manage)`, `Changer les +formations (Sco Change Formation)`, ... +- d'accéder aux vues enseignant pour le département GEII : +Privilèges associés : `Voir les parties pour les enseignants (Sco View Ens)`, +`Saisir des absences (Sco Change Absences)`, ... + +Pour une description plus fine des privilèges, voir +[ConfigPermissions](ConfigPermissions.md) + +### Opérations et cycle de vie des utilisateurs + +Un compte utilisateur peut être modifié par 3 types d'utilisateurs : + +- L'utilisateur lui-même ; +- un administrateur du département de rattachement de l'utilisateur ; +- le super administrateur. + +Les opérations existantes sont : + +- La création ; +- la demande de renouvellement de mot de passe; +- la désactivation. + +#### Notes: + +- La suppression d'un utilisateur est impossible (nécessité de garder la trace + des anciens historiques), mais on peut le rendre inactif (il n'apparait alors + pas dans la liste).) +- Le mécanisme de changement de mot de passe de ScoDoc 7 (par envoi d'un nouveau + mot de passe par mail) a été remplacé par l'ajout de la mention suivante dans + le formulaire de connexion : + + +` En cas d'oubli de votre mot de passe cliquez ici pour le réinitialiser. ` + +#### Création d'un utilisateur (par formulaire) + +La création d'un utilisateur peut être faite par un administrateur ou super +administrateur. Le lien `Ajouter un utlisateur` permettant cela se trouve dans +la page de gestion des utilisateurs (accessible par le menu latéral) + +**Le mot de passe** peut être + +- saisi par le créateur de l'utilisateur (il appartient alors au créateur de + communiquer ce mot de passe à l'utilisateur final); +- ou initialisé à une valeur non communiquée, à charge pour l'utilisateur final + de finaliser la création du mot de passe avant d'utiliser son accès (il y est + invité par un email qui lui est envoyé). + +**Les options de création (mail)** permettent également de choisir parmi les 3 +scenarii suivants : + +1. un message d'accueil l'invitant à initialiser son mot de passe ; +2. un message de bienvenue simple ; +3. aucun message. + +Une case à cocher `envoyer un mail d'accueil à l'utlisateur` permet de choisir +la troisième option (si décochée), sinon la case suivante `indiquer par mail de +changer le mot de passe initial` permet de choisir entre l'option 1 et l'option +2. + +Dans tous les cas les mails seront envoyés avec l'adresse de réponse précidée par la valeur de la variable d'environnement +`SCODOC_MAIL_FROM` (par défaut `no-reply@{serveur_mail}`). Cette variable peut être initialisée dans le fichier .env par exemple avec la ligne: + +```bash +SCODOC_MAIL_FROM=no-reply@univ-exemple.fr +``` + +**Le département d'appartenance** peut être choisi si le créateur est +administrateur pour plusieurs départements. Il aura alors le loisir +de sélectionner l'un des départements qu'il administre (liste déroulante). + +#### Création en masse (fichier xlsx) + +Le super-administrateur (et lui seulement) peut également créer des comptes en +masse par téléversement d'un fichier au format `.xlsx` par le biais du lien +`importer des utilisateurs` de la même page de gestion des utilisateurs. + +La page affichée lui permet d'importer un modèle qu'il doit compléter et re-soumettre à ScoDoc +selon le même schéma que la saisie de note par fichier Excel. + +Les colonnes à remplir sont les suivantes : + +- `user_name`: le nom de connexion de l'utilisateur; (obligatoire, unique dans scodoc) +- `nom`: le nom de l'utilisateur ; (obligatoire) +- `prenom`: le prénom de l'utilisateur ; (obligatoire) +- `email`: l'email de l'utilisateur ; (obligatoire, unique dans scodoc) +- `roles`: le ou les rôles attribués à l'utilisateur séparés par des virgules (exemple `Admin_RT, Ens_GEII`) +- `dept`: le département de rattachement de l'utilisateur (acronyme, en lettres capitales). + +_Note_: + +- Tous les utilisateurs sont créés ou bien aucun. +- Un mail est envoyé à chaque utilisateur nouvellement créé. + +#### Changement du mot de passe + +Deux circonstances sont envisagées. + +##### Oubli de mot de passe + +Lorsqu'un utilisateur a perdu son mot de passe, il a la possibilité de retrouver +son accès sans intervention d'un administrateur. Il lui suffit de demander la +réinitialisation par le lien situé sur la page de connexion. Après renseignement +de son email (qui est maintenant identifiant dans scodoc), un mail lui est +envoyé. ce mail contient un lien comportant un jeton à durée limitée. Ce lien +renvoie vers la page permettant de redéfinir le mot de passe de l'utilisateur. + +##### Edition du profil + +Si l'utilisateur peut se connecter, il peut éditer son profil (et par là, +modifier son email et/ou son mot de passe). La barre latérale de l'écran +principal de scodoc affiche dans le coin supérieur gauche la version courante de +scodoc ainsi que l'identification de l'utilisateur actuel. Un clic sur le nom +permet à l'utilsateur d'éditer son profil. + +#### Activation/désactivation + +Une fois créé, le compte utilisateur conserve son existence. Il peut cependant être rendu inactif: + +- soit à l'expiration de la date de validité spécifiée à la création ou lors d'un modification +- soit directement par un administrateur. + +Quelle que soit la procédure, le compte existe encore et conserve son email (il +n'est donc pas possible de créer un nouveau compte associé au même email). Il +est simplement impossible de se connecter ou de modifier le profil de ce compte +par l'utilisateur lui-même. + +### Implémentation (pour les développeurs) + +Le graphe d'état ci-dessous explicite les différents états que peux prendre un +compte utilisateur en fonction des opérations qu'il subit. + +On notera: + +1. Que la création (1) peut le placer initialement dans deux états différents + selon le mode de création choisi. +2. Que l'on peut demander le renouvellement du mot de passe plusieurs fois même + sans avoir complété la procédure. +3. Que les états `créé`et `créé + ticket`permettent la connexion (sous réserve + de la connaissance du mot de passe). -### Base de données utilisateurs -Il est conseillé de placer la table utilisateurs dans une base de données séparées de celle -des notes, afin de pouvoir la partager entre plusieurs UFRs ou départements sans compromettre -la sécurité des données. Dans l'installation standard ([GuideInstallDebianDix](GuideInstallDebianDix.md)), il s'agit de la base -**SCOUSERS**. + -La table **sco_users** contient: +**SCODOC**. - **Colonne** | **Type** || Contenu - ---------- | ----- | ----- - user_id | text | identifiant interne unique - user_name | text | nom de login - passwd | text | hash password - roles | text | liste des noms de rôles, séparés par des virgules -date_modif_passwd | date | - nom | text | - prenom | text | - email | text | adresse mail - dept | text | département de rattachement (exemple "RT") +La table **user** contient: + +| **Colonne** | **Type** | Contenu | Modifié par | +|-------------------|-----------------------------|--------------------------------------------------------------|----------------| +| id | integer | identifiant interne unique | 1 | +| user_name | character varying(64) | nom de login | 1 | +| email | character varying(120) | adresse mail (unique dans la base) | 1, 6 | +|nom | character varying(64) | | 1, 6 | +|prenom | character varying(64) | | 1, 6 | +|dept | character varying(32) | département de rattachement (identifiant numérique) | 1, 6 | +|active | boolean | | 1, 7, 9 | +|password_hash | character varying(128) | hash password | 1, 6 | +|password_scodoc7 | character varying(42) | deprecated (utilisé lors de la migration scodoc7 > scodoc9) | 1, 2, 4, 5, 6 | +|last_seen | timestamp without time zone | date de dernière connexion | 1, A | +|date_modif_passwd | timestamp without time zone | | 1, 2, 4, 5, 6 | +|date_created | timestamp without time zone | | 1 | +|date_expiration | timestamp without time zone | | 1 | +|passwd_temp | boolean | deprecated | | +|token | text | dernier token émis (changement de mot de passe) | 1a, 3 | +|token_expiration | timestamp without time zone | date d'expiration du dernier token émis | 1a, 3 | -/!\ encodage `utf-8`, sauf si vous avez modifié l'installation. -Pour la signification des rôles et l'utilisation du département, voir [ConfigPermissions](ConfigPermissions.md). + encodage `utf-8`, sauf si vous avez modifié l'installation. + +Pour la signification des rôles et l'utilisation du département, voir +[ConfigPermissions](ConfigPermissions.md). diff --git a/docs/ApiGenerationBulletinsPdf.md b/docs/ApiGenerationBulletinsPdf.md index 278cdc6e8..02e9cc883 100644 --- a/docs/ApiGenerationBulletinsPdf.md +++ b/docs/ApiGenerationBulletinsPdf.md @@ -38,7 +38,7 @@ class [BulletinGeneratorExample](BulletinGeneratorExample.md)(sco_bulletins_stan """Un exemple simple de bulletin de notes en version PDF seulement. Part du bulletin standard et redéfini la partie centrale. """ - description = 'exemple (ne pas utiliser)' # la description doit être courte: elle apparait dans le menu de paramètrage + description = 'exemple (ne pas utiliser)' # la description doit être courte: elle apparait dans le menu de paramétrage supported_formats = [ 'pdf' ] # indique que ce générateur ne peut produire que du PDF (la version web sera donc celle standard de [ScoDoc](ScoDoc.md)) # En général, on veut définir un format de table spécial, sans changer le reste (titre, pied de page). diff --git a/docs/BUT.md b/docs/BUT.md index d6163d4bd..e831aba32 100644 --- a/docs/BUT.md +++ b/docs/BUT.md @@ -1,5 +1,15 @@ -# Le BUT +# Le Bachelor Universitaire de Technologie (BUT) + +Formation en trois ans dispensées par les IUT français, introduite en 2021, et +basée sur une forme d'approche par compétences nécessitant un système +d'évaluation spécifique. + +Cette page décrit les principaux éléments du BUT utiles à comprendre pour le +gérer avec ScoDoc. Pour les curieux, la page +[modélisation des parcours BUT](ModelisationParcoursBUT.md) +donne quelques détails sur la façon dont ScoDoc organise les objets du BUT. + ## UE, modules, évaluations @@ -162,14 +172,33 @@ Les conditions de passages vers l'année suivante sont: 3. Cas particulier du passage en BUT 3: nécessité d’avoir validé toutes les UE du BUT 1. -TODO *à compléter suivant l'arrêté.* -> La validation des deux UE du niveau d’une compétence emporte la validation de -> l’ensemble des UE du niveau inférieur de cette même compétence. +Note: La validation des deux UE du niveau d’une compétence emporte la validation de + l’ensemble des UE du niveau inférieur de cette même compétence. + +### Redoublements +La poursuite d'études dans un semestre pair d’une même année est *de droit* pour +tout étudiant. La poursuite d’études dans un semestre impair est possible si et +seulement si l’étudiant a obtenu : + + - la moyenne à plus de la moitié des regroupements cohérents d’UE ; + - et une moyenne égale ou supérieure à 8 sur 20 à chaque regroupement cohérent +d’UE. La poursuite d'études dans le semestre 5 nécessite de plus la validation +de toutes les UE des semestres 1 et 2 dans les conditions de validation des +points 4.3 et 4.4, ou par décision de jury. + +Durant la totalité du cursus conduisant au bachelor universitaire de +technologie, l'étudiant peut être autorisé à redoubler une seule fois chaque +semestre dans la limite de *4 redoublements*. Le directeur de l'IUT peut autoriser +un redoublement supplémentaire en cas de force majeure dûment justifiée et +appréciée par ses soins. Tout refus d'autorisation de redoubler est pris après +avoir entendu l'étudiant à sa demande. Il doit être motivé et assorti de +conseils d'orientation. ### Obtention du diplôme -TODO à rédiger à partir de l'arrêté. +Le diplôme de BUT est obtenu lorsque toutes les compétences du parcours suivi +sont validées. ### Modules "bonus" (sport, culture, LV2) diff --git a/docs/CalculNotes.md b/docs/CalculNotes.md index 2feea2467..3967b21e1 100644 --- a/docs/CalculNotes.md +++ b/docs/CalculNotes.md @@ -3,6 +3,8 @@ *Tout ce que vous avez toujours voulu savoir sur le calcul des moyennes...* +**Attention :** Les informations ci-dessous s'appliquent aux formations traditionnelles. +Pour les formations par compétences, voir [la page dédiée au BUT](BUT.md). ### En résumé: diff --git a/docs/ConseilServeurDev.md b/docs/ConseilServeurDev.md index 8814ae9a9..da05a0036 100644 --- a/docs/ConseilServeurDev.md +++ b/docs/ConseilServeurDev.md @@ -7,13 +7,38 @@ Quelques indications pour développer avec ScoDoc 7.x, à adapter à vos goûts Il est confortable de développer dans une VM (un container Docker ferait aussi bien l'affaire). -## Conseils pour VirtualBox -[VirtualBox](https://www.virtualbox.org/) est facile à installer sur Mac, Linux ou Windows. Créer une VM avec Debian 10, et suivre la [procédure habituelle d'installation de ScoDoc](GuideInstallDebian11.md). XXX +## Conseils pour la machine virtuelle -En général, vous préférez développer sur la machine hôte pour disposer de votre éditeur préféré. Mais vous exécutez ScoDoc dans la VM. +[VirtualBox](https://www.virtualbox.org/) est facile à installer sur Linux ou +Windows. Créer une VM avec Debian 10, et suivre la [procédure habituelle +d'installation de ScoDoc](GuideInstallDebian11.md). -### Configuration réseau - La VM a besoin d'accéder à Internet pour l'installation, et aussi pour les mises à jour et peut-être certains tests que vous voudrez lancer. L'accès à la VM depuis l'hôte doit être possible via un réseau privé interne (car vous ne serez pas toujours conencté à Internet, et ne souhaitez pas que l'on accède à votre serveur de test de l'extérieur). +Sur les Macs anciens (processeurs Intel), VirtualBox fonctionne bien. Sur les +modèles "M1" (Apple Silicon), je conseille d'utiliser +[UTM](https://mac.getutm.app/) qui est facile à installer et très performant. On +installe alors une VM avec la distribution Linux Debian pour l'architecture +`arm64` (nous ne produisons pas de paquets Debian `arm64` pour ScoDoc 9, mais +l'installation est simple, ne pas hésiter à demander sur le Discord). + +En général, vous préférez développer sur la machine hôte pour disposer de votre +éditeur préféré, mais exécutez ScoDoc dans la VM. + +### Éditeur de texte / IDE +Si vous êtes expérimenté, vous avez vos outils préférés. Mais si vous débutez, +surtout pour un environnement de développement distant (le code développé tourne +dans une machine virtuelle ou réelle séparée de votre machine de burea), nous +vous conseillons **VS Code** avec le module +[*Remote-SSH*](https://code.visualstudio.com/docs/remote/ssh). Ceci vous évite +de fastidieuses configurations de partage de fichiers entre les machine, il +suffit d'une connexion SSH fonctionnelle. + +### Configuration réseau de VirtualBox + +La VM a besoin d'accéder à Internet pour l'installation, et aussi pour les mises +à jour et peut-être certains tests que vous voudrez lancer. L'accès à la VM +depuis l'hôte doit être possible via un réseau privé interne (car vous ne serez +pas toujours conencté à Internet, et ne souhaitez pas que l'on accède à votre +serveur de test de l'extérieur). Modifier la config réseau via l'UI graphique de VirtualBox, la VM étant éteinte. @@ -33,7 +58,8 @@ Dans le Debian, j'utilise `/etc/network/interfaces` (le `enp0s3` désigne chez moi l'`Adapter 1`, mais c'est susceptible de changer. Normalement, l'installeur créé ce fichier ) -Pour lancer l'interface externe , quand on a besoin d'accéder à Internet depuis la VM (en fait assez rarement): +Pour lancer l'interface externe , quand on a besoin d'accéder à Internet depuis +la VM (en fait assez rarement): dhclient enp0s8 @@ -46,13 +72,20 @@ Modifier le `/etc/hosts` (ou équivalent) de l'hôte, et y ajouter l'IP de votre ### Partage de fichiers -Pour éditer votre code au chaud sur votre hôte, il y a plein de solutions. L'une consiste à laisser le code dans la VM, mais de monter un répertoire (par exemple `/opt`) sur l'hôte, par exemple via `sshfs`. +Pour éditer votre code au chaud sur votre hôte, il y a plein de solutions. +La plus simple, déjà mentionnée, consiste à passer par une connexion SSH (VS +Code propose un module dédié très simple et performant, mais tout montage de +type `sshfs`peut aussi faire l'affaire). -Une autre solution (que j'utilise sur mon MacBook), est de laisser le source (clone git) sur l'hôte, et de partager ce répertoire avec la VM. -Dans VirtualBox / config. VM / Dossiers partagés, ajouter un partage. Par exemple, vous mettez vos sources sur l'hôte dans `~/src`, et dans la VM sur `/src`. -Dans ScoDoc, `/opt/scodoc/Products/ScoDoc` est alors un lien symbolique vers votre `src/ScoDoc`. +Une autre solution est de laisser le source (clone git) sur l'hôte, et de +partager ce répertoire avec la VM. Dans VirtualBox / config. VM / Dossiers +partagés, ajouter un partage. Par exemple, vous mettez vos sources sur l'hôte +dans `~/src`, et dans la VM sur `/src`. +Dans ScoDoc, `/opt/scodoc/Products/ScoDoc` est alors un lien symbolique vers +votre `src/ScoDoc`. +#### Détails sur les partages avec VirtualBox Pour pouvoir utiliser des liens symboliques dans le partage: VBoxManage setextradata "Debian11" VBoxInternal2/SharedFoldersEnableSymlinksCreate/src 1 @@ -75,7 +108,7 @@ Il arrive (?) que Virtual Box change les droits unix sur les fichiers partagés. git diff -p -R --no-color | grep -E "^(diff|(old|new) mode)" --color=never | git apply -# Interaction avec ScoDoc 7 +# Interaction avec ScoDoc 7 (ancien ScoDoc, avant l'été 2021) ScoDoc 7 utilise Zope, et ce n'est pas un environnement commode pour débugguer. diff --git a/docs/FAQ.md b/docs/FAQ.md index 4f14ef890..31092bbe4 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -17,7 +17,8 @@ L'avenir du logiciel dépend donc de vous: adhérez, ou incitez votre institutio ## Utilisation de ScoDoc ### Comment prendre en compte les notes de sport ou autres bonus ? -Voir [CalculNotes](CalculNotes.md) +Voir [CalculNotes](CalculNotes.md), ou bien +[le tutoriel vidéo par Cédric C.](https://www.youtube.com/watch?v=SVbjuDpq-lI&list=PLw49h6RbvswhasBk9bXj7PzOD8GDW3kG1&index=13). ### Qui peut voir les notes, et quand ? @@ -100,47 +101,39 @@ garantie. Mais nous faisons de notre mieux: - si vous êtes utilisateurs, écrire à [notes@listes.univ-paris13.fr](mailto:notes@listes.univ-paris13.fr). + ou joindre le canal Discord Assistance. + - si vous êtes informaticien et voulez évoquer un problème technique (développement, installation), écrire à [scodoc-devel@listes.univ-paris13.fr](mailto:scodoc-devel@listes.univ-paris13.fr). - - ## Configuration ### Comment changer les logos sur les documents PDF (PV...) - -Il faut (pour l'instant) être administrateur sur le serveur ScoDoc, et passer -par l'onglet "configuration" accessible aux admins sur la page d'accueil. - -Les logos sont stockés dans le répertoire `/opt/scodoc-data/config/logos/` et -doivent être des images JPEG (extension `.jpg`). Il faut aussi indiquer les -tailles des images dans le fichier de configuration `config/scodoc_config.py`, -variable `CONFIG.LOGO_FOOTER_HEIGHT` etc. - - * Sur les PV, `logo_header.jpg` est affiché en haut, et `logo_header.jpg` en bas de la page. - * Sur les bulletins de notes, c'est configurable (et on peut utiliser d'autres - logos), voir [ParametrageBulletins](ParametrageBulletins.md) - +Il faut avoir un compte (web) administrateur sur ScoDoc, et passer +par l'onglet "configuration" accessible sur la page d'accueil. +Voir [la page sur la gestion des logos et images ](GestionLogos.md). ### Administration ### Quel système d'exploitation ? ScoDoc est accessible depuis n'importe quel navigateur Web (Firefox, Chrome, ...). -Le serveur ScoDoc fonctionne sous linux. Il n'est testé qu'avec Debian (stable). -Le script d'installation ( [GuideInstallDebian11](GuideInstallDebian11.md) ) +Le serveur ScoDoc fonctionne sous Linux. Il n'est testé qu'avec Debian (stable). +Le script d'installation ([GuideInstallDebian11](GuideInstallDebian11.md)) assure l'installation de tout les éléments nécessaires au bon fonctionnement de -ScoDoc. Une distribution sous forme de container Docker est envisagée. - +ScoDoc. ### Quand et comment mettre à jour le logiciel ? +Les mises à jour sont normalement automatiquement appliquées chaque nuit, +assurant la sécurité et l'actualisation de ScoDoc. + Des améliorations et corrections sont fréquemment introduites. Les plus importantes sont annoncées sur la liste de diffusion "[scodoc-annonces](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-annonces)". -Les mises à jour sont normalement automatiquement appliquées chaque semaine. + Voir aussi la page [MisesAJour](MisesAJour.md). diff --git a/docs/GestionJury.md b/docs/GestionJury.md index ab14f4e2f..0fd3e99d6 100644 --- a/docs/GestionJury.md +++ b/docs/GestionJury.md @@ -115,9 +115,8 @@ pour un semestre de formation. Il s'agit d'un document PDF en format paysage, à imprimer sur papier ordinaire A4. -Les logos (IUT en haut, université en pied de page) ne sont actuellement pas -paramétrables par l'utilisateur (il faut installer les images dans le sous-répertoire -`logos` du logiciel). +Les logos (IUT en haut, université en pied de page) sont +paramétrables par l'utilisateur: voir [configuration des logos](GestionLogos.md). ### Lettres d'avis individuelles diff --git a/docs/GestionLogos.md b/docs/GestionLogos.md new file mode 100644 index 000000000..d203d0a8d --- /dev/null +++ b/docs/GestionLogos.md @@ -0,0 +1,53 @@ + +# Gestions des logos et fonds de documents + +Images (logos ou autre) à afficher sur des documents PDF générés par ScoDoc: + + * Sur les PV, `logo_header.jpg` est affiché en haut, et `logo_header.jpg` en bas de la page. + * Sur les bulletins de notes, c'est configurable (et on peut utiliser d'autres + logos), voir [ParametrageBulletins](ParametrageBulletins.md) + * Fonds de page: charger une image nommée `pvjury_background` pour les PV de + jury (en format paysage) ou `letter_background`pour les bulletins et lettres + de jury (en format portrait). Voir [paramétrage des PV](ParametragePV.md). + +Ces images peuvent être chargées ou modifiées par l'administrateur via le menu +"*configuration*" sur la page d'accueil de ScoDoc. + + +## Informations techniques pour les développeurs et administrateurs curieux. + +Normalement, l'administrateur n'a pas besoin d'intervenir dans les répertoires +mentionnés ci-dessous (sauf pour veiller à ce que `/opt/scodoc-data` soit bien +sauvegardé ou transféré lors des migrations). + +La totalité des opérations nécessaires à l'utilisation de ScoDoc peuvent être +réalisées par le menu de configuration des logos. + +### Fichiers et répertoires associés aux logos + +Les images (logos et fonds de document) sont enregistrées dans le répertoire `/opt/scodoc-data/config/logos` et ses sous-répertoires. + +Les images ajoutées par les utilisateurs ont toutes un nom de la forme `logo_.png` ou `logo_.jpg` +(`` représente le nom d'usage du logo : *header*, *footer*, signature, ... au choix de l'utilisateur) +Les sous-répertoires ont des noms de la forme `logos_` où `` est +l'identifiant numérique du département +(la commande `flask list-depts` donne la correspondance cf. [Administration en ligne de commande](GuideConfig.md)). + +Les **fonds de page** se distinguent uniquement des logos par leur nom (`` peut être soit `jpg`ou `png`) : + +| Document | nom | fichier | +|----------------------------------|-------------------------|--------------------------------| +| PV de jury | pvjury_background | `logo_pvjury_background.` | +| bulletin de note | letter_background | `logo_letter_background.` | +| lettre individuelle de décision | letter_background | `logo_letter_background.` | + +### Note: héritage scodoc7 + +Les serveurs ScoDoc 7 utilisaient pour les fonds de page, des fichiers de nom +`letter_background.` et `pvjury_background.`. Lors de la migration +depuis ScoDoc 7, ces fichiers ont placés dans le même répertoire que les images +scodoc9. Pour assurer la compatibilité ascendante, leur présence est +exceptionnellement prise en compte. Bien évidemment, si un fichier scodoc9 (donc +avec le préfixe `logo_`) est présent, il est prioritaire sur le fond de page +"historique". + diff --git a/docs/GuideAdminSys.md b/docs/GuideAdminSys.md index 4d42fdccb..bd9357441 100644 --- a/docs/GuideAdminSys.md +++ b/docs/GuideAdminSys.md @@ -11,10 +11,6 @@ Utilisez un **serveur virtuel** ou un container Docker si vous n'avez pas de mac * Migration d'un serveur ScoDoc 7 vers la nouvelle version Scodoc 9: [MigrationScoDoc7a9](MigrationScoDoc7a9.md) -(Les personnes ayant besoin d'installer l'ancienne version ScoDoc 7 peuvent se -référer à [GuideInstallDebianDix](GuideInstallDebianDix.md) ou -[GuideInstallDebianNeuf](GuideInstallDebianNeuf.md).) - ## Mises à jour et sauvegardes * [Mettre à jour du logiciel (nouvelles versions)](MisesAJour.md) @@ -23,12 +19,14 @@ référer à [GuideInstallDebianDix](GuideInstallDebianDix.md) ou ## Configuration et préférences + * [Administration en ligne de commande](GuideConfig.md) * [ConfigPermissions](ConfigPermissions.md) : description des permissions et rôles utilisés par le système. - * [ Paramétrage](PreferencesScoDoc.md): réglage des préférences + * [Paramétrage](PreferencesScoDoc.md): réglage des préférences ## Autres problèmes * [Problèmes configuration des envois mail](ProblemesMail.md) + * [Gestion des logos et fonds de documents](GestionLogos.md) * [ProblemesEtBugs](ProblemesEtBugs.md) en cas d'ennuis. ## Utilisation avancée diff --git a/docs/GuideConfig.md b/docs/GuideConfig.md index 7eee76d1f..24eff04a0 100644 --- a/docs/GuideConfig.md +++ b/docs/GuideConfig.md @@ -1,15 +1,14 @@ -# Prise en main et paramétrage de ScoDoc 9 +## Prise en main et paramétrage de ScoDoc 9 /!\ Cette -page concerne la version ScoDoc 9, distribuée à partir de septembre 2021. Pour l'ancienne -version, voir [cette page](GuideConfig7.md). +page concerne la version ScoDoc 9, distribuée à partir de septembre 2021. Ce document suppose que le logiciel a été installé suivant la procédure décrite dans [GuideInstallDebian11](GuideInstallDebian11.md). -# Administration en ligne de commande +## Administration en ligne de commande Les opérations d'administration se résument à la création de départements, et l'installation des logos, et la création d'utilisateurs "super admin", c'est à dire admin pour tous les @@ -32,30 +31,30 @@ Après quoi, vous pouvez utiliser les commandes décrites ci-dessous. *Attention: le lancement de chaque commande est assez long (quelques secondes) car toute l'application scodoc est initialisée à chaque fois.* -## Création d'un département +### Création d'un département flask create-dept DEPT où `DEPT` est l'acronyme du département, par exemple "RT". Ce département apparait immédiatement sur la page d'accueil. -## Suppression d'un département +### Suppression d'un département Opération très rarement nécessaire, proposée pour corriger une erreur immédiatement après la création. flask delete-dept DEPT -## Création d'un utilisateur +### Création d'un utilisateur Cette opération s'effectue en général depuis le logiciel, via un formulaire -ou un import excel. Pour créer un utilisateur depuis le terminal, lancer: +ou un import Excel. Pour créer un utilisateur depuis le terminal, lancer: flask user-create LOGIN ROLE DEPT où `LOGIN` sera le pseudo de l'utilisateur (utilisé pour se connecter), et `ROLE` le rôle (`Ens`, `Secr`, `Admin`) dans le département `DEPT`. -## Création d'un super-administrateur +### Création d'un super-administrateur Il s'agit d'un utilisateur ayant tous les droits, comme s'il était `Admin` dans tous les départements. @@ -64,7 +63,7 @@ Il s'agit d'un utilisateur ayant tous les droits, comme s'il était où `admin2` est ici le pseudo du nouvel admin. -## Changement du mot de passe d'un utilisateur +### Changement du mot de passe d'un utilisateur Cette opération peut s'effectuer via la page de gestion web des utilisateurs, mais il est parfois commode de le faire depuis la console: @@ -74,21 +73,21 @@ console: où `LOGIN` est le pseudo de l'utilisateur. Le mot de passe est demandé sur la ligne de commande. -## Création d'un nouveau rôle +### Création d'un nouveau rôle flask create-role role_name [permissions...] -Exemple: création d'une rôle "Observateur" ayant juste la persmision de "voir": +Exemple: création d'une rôle "Observateur" ayant juste la permission de "voir": flask create-role Observateur ScoView -## Édition d'un rôle (ajout/retrait permissions) +### Édition d'un rôle (ajout/retrait permissions) flask edit-role [-a permission] [-r permission] role_name Ajoute ou retire une permission. -## Ajout/retrait d'un rôle à un utilisateur +### Ajout/retrait d'un rôle à un utilisateur flask user-role username [-d departement] [-a RoleAAjouter] [-r RoleARetirer] @@ -103,7 +102,7 @@ Si le département n'est pas spécifié, le rôle est donné dans *tous* les départements (utile pour certains compte administrateurs ou utilisés en lecture par des clients de l'API). -## Migration des données de ScoDoc 7 +### Migration des données de ScoDoc 7 Les données dans ScoDoc 9 ayant un format et une organisation très différents de ScoDoc 7, une étape de conversion (migration) est nécessaire. Elle est automatique mais prend du temps. @@ -113,14 +112,14 @@ Se reporter à [MigrationScoDoc7a9](MigrationScoDoc7a9.md) Ces commandes sont utilisées par le script de migration de ScoDoc 7 à ScoDoc 9. *Ne pas utiliser sauf si vous savez vraiment ce que vous faites.* -### Comptes utilisateurs +#### Comptes utilisateurs Toujours migrer les comptes utilisateurs avant d'importer les départements. flask import-scodoc7-users -### Départements +#### Départements Pour migrer un seul département: flask import-scodoc7-dept DEPT DBNAME @@ -129,14 +128,19 @@ Exemple: flask import-scodoc7-dept InfoComm DBINFOCOMM -## Liste des commandes Flask/ScoDoc +### Liste des commandes Flask/ScoDoc ``` +Usage: app [OPTIONS] COMMAND [ARGS]... + +Options: + --help Show this message and exit. + Commands: clear-cache Clear ScoDoc cache This cache (currently... create-dept Create new departement create-role Create a new role - delete-role Delete a role delete-dept Delete existing departement + delete-role Delete a role dumphelp edit-role Add [-a] and/or remove [-r] a permission... import-scodoc7-dept Import département ScoDoc 7: dept:... @@ -151,7 +155,8 @@ Commands: scodoc-database print the database connexion string user-create Create a new user user-db-clear Erase all users and roles from the... - user-password Set (or change) user's password + user-delete Try to delete this user. + user-password Set (or change) user’s password user-role Add or remove a role to the given user... Usage: app sco-db-init [OPTIONS] @@ -161,14 +166,12 @@ Usage: app sco-db-init [OPTIONS] Options: --erase / --no-erase - --help Show this message and exit. Usage: app user-db-clear [OPTIONS] Erase all users and roles from the database ! -Options: - --help Show this message and exit. + Usage: app user-create [OPTIONS] USERNAME ROLE DEPT @@ -177,22 +180,23 @@ Usage: app user-create [OPTIONS] USERNAME ROLE DEPT Options: -n, --nom TEXT -p, --prenom TEXT - --help Show this message and exit. + +Usage: app user-delete [OPTIONS] USERNAME + + Try to delete this user. Fails if it’s associated to some scodoc objects. + Usage: app user-password [OPTIONS] USERNAME - Set (or change) user's password + Set (or change) user’s password Options: --password TEXT - --help Show this message and exit. Usage: app create-role [OPTIONS] ROLENAME [PERMISSIONS]... Create a new role -Options: - --help Show this message and exit. Usage: app edit-role [OPTIONS] ROLENAME @@ -205,7 +209,13 @@ Usage: app edit-role [OPTIONS] ROLENAME Options: -a, --add TEXT -r, --remove TEXT - --help Show this message and exit. + +Usage: app delete-role [OPTIONS] ROLENAME + + Delete a role + +Options: + --help Show this message and exit. Usage: app user-role [OPTIONS] USERNAME @@ -222,22 +232,20 @@ Usage: app delete-dept [OPTIONS] DEPT Delete existing departement Options: + --yes --help Show this message and exit. Usage: app create-dept [OPTIONS] DEPT Create new departement -Options: - --help Show this message and exit. Usage: app list-depts [OPTIONS] [DEPTS]... If dept exists, print it, else nothing. Called without arguments, list all depts along with their ids. -Options: - --help Show this message and exit. + Usage: app scodoc-database [OPTIONS] @@ -246,7 +254,7 @@ Usage: app scodoc-database [OPTIONS] Options: -n, --name show database name instead of connexion string (required for dropdb/createdb commands) - --help Show this message and exit. + Usage: app import-scodoc7-users [OPTIONS] @@ -255,54 +263,43 @@ Usage: app import-scodoc7-users [OPTIONS] script is typically run as unix user "scodoc". The original SCOUSERS database is left unmodified. -Options: - --help Show this message and exit. Usage: app import-scodoc7-dept [OPTIONS] DEPT DEPT_DB_NAME Import département ScoDoc 7: dept: InfoComm, dept_db_name: SCOINFOCOMM -Options: - --help Show this message and exit. Usage: app migrate-scodoc7-dept-archives [OPTIONS] [DEPT] Post-migration: renomme les archives en fonction des id de ScoDoc 9 -Options: - --help Show this message and exit. Usage: app migrate-scodoc7-dept-logos [OPTIONS] [DEPT] Post-migration: renomme les logos en fonction des id / dept de ScoDoc 9 -Options: - --help Show this message and exit. Usage: app localize-logo [OPTIONS] LOGO DEPT Make local to a dept a global logo (both logo and dept names are mandatory) -Options: - --help Show this message and exit. Usage: app photos-import-files [OPTIONS] FORMSEMESTRE_ID XLSFILE ZIPFILE -Options: - --help Show this message and exit. + Import des photos d’étudiants à partir d’une liste excel et d’un zip avec les images. Usage: app clear-cache [OPTIONS] Clear ScoDoc cache This cache (currently Redis) is persistent between - invocation and it may be necessary to clear it during development or tests. + invocation and it may be necessary to clear it during upgrades, development + or tests. Options: - --help Show this message and exit. + --sanitize / --no-sanitize Usage: app dumphelp [OPTIONS] -Options: - --help Show this message and exit. + Génère la page d’aide complète pour la doc. Usage: app profile [OPTIONS] @@ -316,41 +313,32 @@ Options: --help Show this message and exit. ``` -## Changement des logos apparaissant sur les documents +(*la liste ci-dessus est générée à l'aide de la commande* `flask dumphelp`). + +### Changement des logos apparaissant sur les documents *Note: après migration, vos logos de ScoDoc 7 sont installés dans ScoDoc 9*. Les documents PDF (PV de jurys...) incluent les logos de l'établissement. Par défaut, ceux de l'IUT de Villetaneuse et de l'Université Paris 13 sont -distribués. Pour les changer, placer vos logos (fichiers images JPEG ou PNG) -dans le répertoire +distribués. [Pour les changer, voir la FAQ](/FAQ/#comment-changer-les-logos-sur-les-documents-pdf-pv) + +Si vous êtes administrateur système, vous pouvez aussi placer vos images (fichiers JPEG ou PNG) +dans le répertoire /opt/scodoc-data/config/logos -avec les noms `logo_header.jpg` (habituellement le logo de votre composante) -et `logo_footer.jpg` (habituellement le logo de votre université ou école). - -On peut fournir des logos par département en créant des sous-répertoires +On peut fournir des images (logos, fond de pages) par département en créant des sous-répertoires /opt/scodoc-data/config/logos/logo_/ -pour y placer les fichiers images `logo_header.jpg` et `logo_footer.jpg`. - - - -Enfin, redémarrez ScoDoc après avoir vidé les caches: +Après quoi, redémarrez ScoDoc après avoir vidé les caches: flask clear-cache sudo systemctl restart scodoc9 -# Utilisation via le Web +## Utilisation via le Web * Connectez-vous au site: `https://votre.site.fr/` diff --git a/docs/GuideConfig7.md b/docs/GuideConfig7.md deleted file mode 100644 index fadde4dfa..000000000 --- a/docs/GuideConfig7.md +++ /dev/null @@ -1,94 +0,0 @@ - -# Prise en main et paramétrage de ScoDoc 7 - -/!\ Cette page -concerne la version ScoDoc 7, et ne s'applique pas à la version ScoDoc 9 distribuée à partir de septembre 2021. -Pour ScoDoc 9, voir [cette page](GuideConfig.md). - -Ce document suppose que le ScoDOc 7 a été installé suivant la procédure décrite dans [GuideInstallDebianDix](GuideInstallDebianDix.md). - - - -## Procédure à suivre pour créer un département et son utilisateur administrateur - * Connectez-vous au site: `https://votre.site.fr/` - - -Vous allez voir la page d'accueil de ScoDoc (il est possible que votre -navigateur vous demande d'accepter un certificat). - -Il n'y a pas de "département défini": c'est normal, lors de l'installation nous -avons créé des bases de données, mais pas les interfaces web. - - * Suivez le lien *Identifiez vous comme administrateur*. L'utilisateur *admin* - est administrateur et a tous les droits sur !ScoDoc. C'est le seul à pouvoir - créer un nouveau département. - -Le logiciel va vous demander de changer immédiatement le mot de passe administrateur. -Entrez l'identifiant et le mot de passe définis pendant l'installation. - -Après vous être identifié sur la page d'accueil ScoDoc, vous avez maintenant un -lien 'Administration de ScoDoc' qui vous permet d'ajouter un département, puis des utilisateurs. - - * Ajouter un département (donnez le nom du département créé pendant l'installation) - - * Ajouter un administrateur pour votre département: lien "Utilisateurs" (marge - de gauche), puis suivre "ajouter un utilisateur". Donner à ce nouvel - utilisateur les rôles `Admin`, `Ens` et `Secr` afin qu'il puisse effectuer - toutes les opérations. - -Quittez votre navigateur et reconnectez vous à ScoDoc avec votre nouvel utilisateur. - -Vous pouvez si nécessaire créer plusieurs administrateurs par département (il -est préférable que chaque compte ne soit utilisé que par une seule personne, -pour éviter de divulguer les mots de passe et mieux suivre les opérations). - - Surtout, évitez de travailler comme "admin": cet utilisateur doit -être réservé à la création de départements. Prenez le temps de créer un -utilisateur "chef de département !". - - - -## Changement des logos apparaissant sur les documents -Les documents PDF (PV de jurys...) incluent les logos de l'établissement. Par -défaut, ceux de l'IUT de Villetaneuse et de l'Université Paris 13 sont -distribués (ce n'est pas bien, ils ne sont sans doute pas sous licence libre !). -Pour les changer, placer vos logos (fichiers images JPEG ou PNG) dans le -répertoire -``` -/opt/scodoc-data/config/logos -``` -(en ScoDoc 7, c'était `/opt/scodoc/var/scodoc/config/logos`) - -avec les noms `logo_header.jpg` (habituellement le logo de votre composante, -mais faites comme vous voulez) et `logo_footer.jpg` (habituellement le logo de -votre Université ou école). - -Ensuite, éditez le fichier -``` -/opt/scodoc-data/config/scodoc_local.py -``` -(le créer s'il n'existe pas). -Ce fichier doit contenir un dictionnaire sous la forme suivante: -``` -CONFIG = { - # Taille du l'image logo: largeur/hauteur - # W/H - CONFIG.LOGO_FOOTER_ASPECT = 326 / 96.0 - # Taille dans le document en millimetres - CONFIG.LOGO_FOOTER_HEIGHT = 10 - # Proportions logo (donné ici pour IUTV) - CONFIG.LOGO_HEADER_ASPECT = 549 / 346.0 - # Taille verticale dans le document en millimetres - CONFIG.LOGO_HEADER_HEIGHT = 28 - ... autres variables de configuration locale -} -``` - -Adaptez les valeurs des variables `LOGO_FOOTER_ASPECT` et suivantes à votre cas -(ce n'est pas pratique, il faudrait modifier le code ScoDoc pour calculer ces -valeurs à partir des fichiers images). - - -Enfin, redémarrez ScoDoc (`/etc/init.d/scodoc start`). - diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index 6be84be9c..7145b0066 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -20,17 +20,17 @@ Informations pour les développeurs souhaitant étendre ou modifier ScoDoc. Quelques conseils, indications et mémos pour les développeurs sur ScoDoc version 9. ### Installation d'un serveur de développement -[Quelques conseils mouvants pour configurer votre serveur de développement](ConseilServeurDev.md) +[Quelques conseils pour configurer votre serveur de développement](ConseilServeurDev.md) ### Style et formatage du code L'ancienneté de la base de code a rendu le style un peu incohérent, mais cela -s'est amélioré avec ScoDoc 9 (respect PEP 8). +s'est nettement amélioré avec ScoDoc 9 (respect PEP 8). -Le code doit être formatté avec [`black`](https://black.readthedocs.io/) avant +Le code DOIT être formatté avec [`black`](https://black.readthedocs.io/) avant tout commit (configurez votre éditeur pour appeler `black` à l'enregistrement). #### Documentation -On adoptera le style "Google": +On pourra adopter le style "Google": Exemple: """Description résumée de la fonction @@ -58,14 +58,16 @@ Exemple: Le dépôt est -La branche `master` est celle de ScoDoc 9. La branche `Scodoc7` est l'ancienne -(jusqu'à septembre 2021) version en production. +La branche `master` est celle de ScoDoc 9, d'où sont issues les paquets +distribués (*releases*). Les développements ont lieu sur d'autres branches +(`api`, `dev92`, `entreprises`, ...) avant d'être intégrés après tests. +La branche `Scodoc7` était l'ancienne (jusqu'à septembre 2021) version de ScoDoc. Ci-dessous quelques pense-bête qui peuvent servir. #### Hot fixes (internes) Pour les développeurs internes (écriture sur le dépôt master), un exemple -basique: +basique illustrant le cycle de développement: # Créer une branche # si besoin (travail en cours), utiliser git stash avant @@ -82,10 +84,13 @@ basique: # éventuellement: git stash pop +Dans la plupart des cas, on travaillera sur son propre dépot (clone du dépt +origine), et on proposera une *pull request* (PR, *demande d'ajout* en français). + #### Mettre à jour votre branche -Vous travaillez dans votre branche `ma_branche`. Pour lui appliquer les mises à -jour de `master` (remote): +Quand vous travaillez dans votre branche `ma_branche`, pour lui appliquer les +mises à jour de `master` (remote), faire: ```bash git pull origin master ``` @@ -388,6 +393,36 @@ Au besoin, mémo: - `flask clear-cache` efface le cache Redis. +## Re-création du virtualenv + +ScoDoc est livré avec un "virtualenv", qui contient tous les modules python +nécessaires. Il se trouve sous `/opt:scodoc/venv`. +Si vous souhaitez repartir de zéro, tester de nouvelles versions de certaines +bibliothèques, ou autres expériences de ce genre, vous pouvez le récréer ainsi: +```bash + # en tant qu'utilisateur scodoc + cd /opt/scodoc + /bin/rm -rf venv # ou mv ... + python3 -m venv venv + source venv/bin/activate + pip install wheel +``` +Puis soit vous installez les versions "officielles" (testées) +``` + pip install -r requirements-3.9.txt +``` +Soit vous prenez les version les plus à jour disponibles. Une façon rapide de +faire ceci est: +```bash + cut -d= -f 1 requirements-3.9.txt | xargs pip install +``` +à adapter selon vos objectifs. +Pour régénérer le fichier indiquant la liste des paquets: +```bash + pip freeze > requirements-3.9.txt +``` + +Note: la mise à jour par `apt` recrée le virtualenv à chaque fois. ## Roadmap Sujets **prioritaires** en 2021: diff --git a/docs/GuideInstallDeb5.md b/docs/GuideInstallDeb5.md deleted file mode 100644 index b4e00c251..000000000 --- a/docs/GuideInstallDeb5.md +++ /dev/null @@ -1,4 +0,0 @@ - -/!\ '''Attention: document obsolète pour une version ancienne de Debian. Voir [GuideInstallDebianDix](GuideInstallDebianDix.md) pour l'installation normale de !ScoDoc ! - - diff --git a/docs/GuideInstallDebian11.md b/docs/GuideInstallDebian11.md index 5d5cdf2ec..c7a778fd0 100644 --- a/docs/GuideInstallDebian11.md +++ b/docs/GuideInstallDebian11.md @@ -110,10 +110,29 @@ Checklist minimale de votre système Linux Debian: #### Configuration si utilisation d'un proxy Si votre accès à Internet passe par un proxy, l'indiquer au moment de - l'installation Debian. Il est possible qu'il vous faille configurer d'autres + l'installation Debian. + + Ensuite, dans ScoDoc, indiquer votre proxy: pour cela, éditer le fichier + ```/opt/scodoc/.env``` +et ajouter les variables d'environnement nécessaires. Typiquement, il s'agit de : +``` + HTTP_PROXY=http://proxy.univ-xxx.fr:1234 + HTTPS_PROXY=http://proxy.univ-xxx.fr:1234 +``` +Vérifiez aussi que ces variables sont bien définies dans `/etc/environment` +(si l'installeur Linux Debian ne les a pas déjà indiquées là, les ajouter ou créer ce fichier). + +Après modification de ce fichier (qui _doit_ être lisible par l'utilisateur `scodoc`), +redémarrer le service: +``` + sudo systemctl restart scodoc +``` + + Dans les cas compliqués, il est possible qu'il vous faille configurer d'autres éléments, voir par exemple [ce post sur Stack Overflow]( https://stackoverflow.com/questions/9445489/performing-http-requests-with-curl-using-proxy). + #### Note sur l'install dans un container LXC diff --git a/docs/GuideInstallDebianDix.md b/docs/GuideInstallDebianDix.md deleted file mode 100644 index f41e041c3..000000000 --- a/docs/GuideInstallDebianDix.md +++ /dev/null @@ -1,162 +0,0 @@ - -# Installation de ScoDoc sur Debian 10 (Buster) -Ce document décrit la procédure d'installation et de configuration de ScoDoc. -Cette procédure doit être effectué sur la machine serveur avec un accès administrateur (root). - -*Si vous avez déjà une installation ScoDoc version 7 (en Debian 7, 8 ou 9), voir aussi [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md)* - -ScoDoc est livré avec des scripts d'installation qui configurer presque automatiquement votre serveur (serveur web, base de données, etc): vous pouvez donc installer et configurer ScoDoc avec des connaissances réduites sur le système Linux. - -Cette documentation est prévue pour installer ScoDoc sur un système [Debian](http://www.debian.org) 10 (Buster) s'exécutant sur une machine intel-like **64bits** (architecture **AMD64**). Debian s'installe facilement en une quinzaine de minutes, sur une machine normale ou un serveur virtualisé. Il est **très déconseillé** de tenter l'installation sur une autre version, à moins de disposer de temps et de bonnes connaissances sur Linux et les paquetages Python. - -Merci de me signaler tout problème (emmanuel.viennet@gmail.com) - - -- Note 1: l'image du CD d'installation de Debian (amd64) peut se trouver ici: [https://www.debian.org/distrib/netinst](https://www.debian.org/distrib/netinst.md), choisir une version "petits CD" pour **amd64** (*Il est indispensable d'utiliser une version 64 bits ! *) - -- Note 2: si quelqu'un produit, teste et documente une image Docker, merci de la partager (écrire à scodoc-devel). - - -/!\ Important: La procédure d'installation décrite ci-dessous suppose que ScoDoc va s'exécuter sur un serveur dédié. Pour faire des tests, utilisez un serveur virtuel (comme VirtualBox ou VMWare). L'installation ci-dessous va en effet modifier de nombreux paramètres de votre système linux (serveur web, firewall, serveur SQL, messagerie, ...). - - -## Préalable: configurer un serveur linux -Le serveur devrait être accessible depuis Internet. Seul le port 443 (https) est utilisé par ScoDoc. Il est recommandé que le serveur puisse envoyer du mail (smtp). - -Nous recommandons d'effectuer une installation standard de Debian par le réseau (netinst). -Durant l'installation de Debian, lorsqu'il demande "logiciels à installer", tout décocher sauf "Serveur SSH" et "Utilitaires standard du système". Le script d'installation de ScoDoc se chargera ensuite d'installer tous les éléments nécessaires (serveur web, messagerie, etc.). - -![InstallDebian6-1.png](screens/InstallDebian6-1.png) - -### Points à vérifier avant d'installer ScoDoc -Checklist minimale de votre système Linux Debian: - - 1. Connexion à Internet: le réseau doit être accessible. En effet, le script d'installation va installer des paquetages du système Debian puis télécharger la dernière mise à jour du logiciel ScoDoc (à partir du serveur Subversion). - 1. Vérifiez la connectivité, par exemple: -``` -ping www.univ-paris13.fr -(quitter avec ctrl-c) -cd /tmp -wget --no-check-certificate https://www-lipn.univ-paris13.fr/projects/scodoc -# doit créer un fichier nomme "scodoc" contenant du code HTML -``` - 3. Nom DNS: le serveur doit avoir un nom ("serveur.exemple.fr") connu dans le DNS (local ou public). Pour des tests, vous pouvez vous passer de DNS, mais dans ce cas le nom de votre serveur sera son adresse IP (eg 192.168.0.10) et il ne sera peut être pas accessible de l'extérieur. - 1. Vérifiez que votre serveur est accessible depuis une autre machine de votre réseau (voire d'Internet): par exemple "ping serveur.exemple.fr". - 1. Date et heure: vérifier que les dates et heure sont correctes, même après reboot. L'utilisation d'un serveur de temps (ntp) est recommandée (`aptitude install ntp`), et éventuellement `dpkg-reconfigure tzdata`). - 1. Cette liste est très incomplète... et n'oubliez pas: avant de passer en production, mettez en place des sauvegardes sérieuses ! - - -#### Configuration si utilisation d'un proxy -Si votre serveur doit passer par un proxy pour accéder à Internet: - 1. Configurer wget: placer ceci dans `/root/.bashrc` (par exemple) -``` -export http_proxy=http://my-proxy-server.com:my-proxy-port/ -export https_proxy=$http_proxy -``` - - 2. Configurer le client svn - dans `/root/.subversion/servers` dé-commenter et compléter les lignes: -``` -[global] -http-proxy-host = my-proxy-server -http-proxy-port = my-proxy-port -``` -(attention bien enlever l'espace du début de ligne). - - -## Installation de ScoDoc - 1. Récupérer et ouvrir le logiciel (en tant que root): -``` - sudo su # si necessaire pour passer root - cd /opt - wget http://www-l2ti.univ-paris13.fr/~viennet/ScoDoc/builds/scodoc-1851.tgz - tar xfz scodoc-1851.tgz -``` -Cette archive contient ScoDoc, Zope et quelques outils tiers. -/!\ vous pouvez installer ailleurs que dans /opt, mais il faudra alors éditer plusieurs scripts (non recommandé). - - -/!\ Les commandes ci-dessous sont à exécuter dans un terminal ouvert en tant que **root** sur le serveur. Vous pouvez utiliser `su` (ou `sudo su`) pour devenir **root**). - - 1. **Mettre à jour les sources**. Va télécharger les sources à jour, et le script d'installation: -``` - cd /opt/scodoc/Products/ScoDoc - apt install subversion - svn up -``` - - - - 3. **Configurer le logiciel**. Attention: durant cette étape, de nombreux paquets et fichiers de configuration de votre système linux vont être modifiés. Si vous préférez effectuer vous même l'installation (vous êtes développeur ou avez des besoins particuliers), lisez et adaptez le script. - -/!\ je répète, le script `install_debian10.sh` va reconfigurer beaucoup de choses sur votre serveur. Il suppose que la machine vient d'être installée et en gros qu'elle va servir principalement pour ScoDoc. - -Toujours en tant qu'utilisateur root: -``` - cd /opt/scodoc/Products/ScoDoc/config - ./install_debian10.sh -``` -Répondez oui (Y) à toutes les questions, sauf, si vous avez une bonne raison de faire autrement. -En cas d'échec, ce script peut être relancé (il écrasera l'ancienne configuration). - -Dans cette étape, sont installés et configurés automatiquement: - - * serveur web Apache (et https) - * parefeu réseau (optionnel, basé sur `ufw`) - * messagerie pour envois messages (postfix) (optionnel mais très vivement recommandé) - * installation de divers logiciels utilisés par ScoDoc (par apt-get) - * script de lancement automatique de ScoDoc (service systemd). - -(dans certains cas, l'installateur vous posera des questions sur votre configuration). - - - 4. **Initialiser la base de données utilisateurs** (qui sera commune à tous les départements). -En tant que root: -``` - cd /opt/scodoc/Products/ScoDoc/config - ./create_user_db.sh -``` - - 5. **Mettre à jour le logiciel** (c'est absolument nécessaire, la version préinstallée étant incomplète): -En tant que root, -``` - cd /opt/scodoc/Products/ScoDoc/config - ./upgrade.sh -``` -La première fois, il faudra accepter un certificat cryptographique, répondre "p (accept (p)ermanently)". - -/!\ Si un message d'erreur apparaît à la fin de la mise à jour, relancer `./upgrade.sh`. - - -Si vous migrez les données d'une installation existante, vous pouvez arrêter ici et appliquer la procédure [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md) - - 6. **Initialiser la base de données pour un département** (vous pourrez à tout moment utiliser la même commande pour ajouter d'autres départements): -``` - ./create_dept.sh -n DEPT -``` -Il faut alors saisir le nom abrégé du département: ce nom doit être un mot, sans ponctuation (GEII, RT, Info, ...). Il apparaîtra dans l'URL du site correspondant. - - 7. **Lancer ScoDoc**: -``` - systemctl restart scodoc -``` -et voila ! - -Visiter `https://votre.site.fr/` pour achever la configuration et utiliser le logiciel: voir la page [GuideConfig](GuideConfig.md) - - - -## En cas de problème -Ne pas hésiter à me contacter ou à écrire sur la liste notes (voir [Listes de diffusion](ListesDeDiffusion.md)). - - * Problèmes d'envoi de courrier électronique (mail): voir [ProblemesMail](ProblemesMail.md) - -Nota: sur certains réseaux, l'autoconfiguration IPv6 pose problème (par exemple: bloquage des envois de mails). Au besoin, il est possible de désactiver IPv6 (voir par exemple [ici](https://wiki.debian-fr.xyz/D%C3%A9sactiver_l%27IPv6)). - - -## Ensuite... - * Appliquez fréquemment les [mises à jour](MisesAJour.md) - - * Mettez en place des [sauvegardes](SauvegardesBases.md) - - * Abonnez vous au moins à la liste d'annonces: voir [Listes de diffusion](ListesDeDiffusion.md) diff --git a/docs/GuideInstallDebianNeuf.md b/docs/GuideInstallDebianNeuf.md deleted file mode 100644 index ddc88c92b..000000000 --- a/docs/GuideInstallDebianNeuf.md +++ /dev/null @@ -1,8 +0,0 @@ -# Guide d'installation sur Debian 9 - -Version ancienne de Debian, nous recommandons d'utiliser la nouvelle version. -Voir [installation sur Debian 10](GuideInstallDebianDix.md). - -Si besoin, se reporter à [l'ancienne documentation pour Debian 9](https://trac.lipn.univ-paris13.fr/projects/scodoc/wiki/GuideInstallDebianNeuf). - - diff --git a/docs/Internals.md b/docs/Internals.md index 9888e8e24..15516c77d 100644 --- a/docs/Internals.md +++ b/docs/Internals.md @@ -25,8 +25,7 @@ l'ORM SQLAlchemy (recommandé pour tout nouveau code). Les modèles correspondant sont déclarés dans `/opt/scodoc/app/models/`. -Principales classes (le nom de certaines classes Python est donné en -`CaractèresCommeCa`). +Principales classes (les noms des classes Python sont en `CamelCase`). - Étudiants (classe `Identite`): nom, codes INE/NIP, etc - Formations: programmes pédagogiques, contenant @@ -72,4 +71,20 @@ def un_exemple(): formation=formation, ... # etc ) -``` \ No newline at end of file +``` + +# Caches + +Il est bon de savoir que les requêtes SQL de SQLAlchemy ne sont pas cachées: ni +la requête elle même (construction du SQL à partir des appels à l'ORM), ni son +résultat. + +Le module `sco_cache.py` offre la possibilité de cacher des objets python +identifiés par un id unique dans le cache Redis. Ce cache est persistant, il +faut donc invalider les objets quand on écrit des données susceptibles de les +modifier, et penser à le vider quand on modifie le code. +Par exemple: +``` + git pull + flask clear-cache +``` diff --git a/docs/MigrationDonneesScoDoc.md b/docs/MigrationDonneesScoDoc.md index da5a94f6d..d22e727fc 100644 --- a/docs/MigrationDonneesScoDoc.md +++ b/docs/MigrationDonneesScoDoc.md @@ -25,7 +25,7 @@ Le principe est donc: ## Marche à suivre détaillée ### Installation de Debian et ScoDoc - Voir les instructions ici: [GuideInstallDebianDix](GuideInstallDebianDix.md) (ou si votre système est encore en Debian 9: [GuideInstallDebianNeuf](GuideInstallDebianNeuf.md) : mais ce n'est pas conseillé) + Voir les instructions ici: [GuideInstallDebian11](GuideInstallDebian11.md). diff --git a/docs/MisesAJour.md b/docs/MisesAJour.md index 8781dfdc4..d404bfbb2 100644 --- a/docs/MisesAJour.md +++ b/docs/MisesAJour.md @@ -9,140 +9,3 @@ lancer une à tout moment avec la commande apt update && apt-get upgrade - -# Mises à jour de ScoDoc 7 -**Les instructions ci-dessous concernent ScoDoc 7 uniquement.** - -Le système Linux doit être correctement maintenu (en particulier, les mises à -jour de sécurité de Debian doivent être appliquées quotidiennement). - -ScoDoc est actuellement prévu pour fonctionner avec Linux Debian 10. - - * Les (rares) mises à jour majeures du logiciel ScoDoc sont annoncées sur la - liste - [scodoc-annonces](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-annonces). - - * Les (fréquentes) mises à jour mineures (corrections de bugs, améliorations) - sont annoncées sur la liste - [scodoc-devel](https://listes.univ-paris13.fr/mailman/listinfo/scodoc-devel). - - -*Une mise à jour hebdomadaire (au moins) est recommandée* - -Pour appliquer une mise à jour de ScoDoc, se connecter en tant que `root` sur le -serveur, puis faire: - - cd /opt/scodoc/Products/ScoDoc/config - ./upgrade.sh - -La première fois, il faudra accepter un certificat cryptographique, répondre "p -(accept (p)ermanently)". - - Si un message d'erreur apparaît à la fin de la mise à jour, -relancer `./upgrade.sh`. - - La mise à jour entraine une déconnexion des utilisateurs (mais pas -de pertes de données !). - -Note: cette procédure ne change pas de version majeure de ScoDoc, ni du système -Linux. Pour cela, voir [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md)) ou -plus bas sur cette page. - -## Note concernant les anciens systèmes (Debian 9) - -En Debian version 9 (et version antérieures), ScoDoc n'utilisait pas `systemd` -et n'était pas automatiquement relancé lors de mises à jour de certains -logiciels, comme la base de données `postgresql`. Sur ces systèmes, il est -conseillé de mettre à jour Debian avec le script -`/opt/scodoc/Products/ScoDoc/config/upgrade.sh` afin d'éviter d'interrompre le -service ScoDoc. - - -## Mise à jour rapide de Debian 9 à Debian 10 (obsolète) - -Obsolète, sauf si vous avez encore un serveur avec Debian 9... - -Procédure raccourcie réservée aux personnes à l'aise avec linux. On met à jour -Debian mais on réinstalle ScoDoc proprement. - -Vérifiez que vous avez assez d'espace disque disponible (`df -h`, au moins 3Go -libres sur `/` ou `/opt`). - - 0. Sauvegardez complètement votre système en lieu sûr. Si la procédure - ci-dessous échoue, reprenez la voie normale: - [MigrationDonneesScoDoc](MigrationDonneesScoDoc.md). - - 1. Mettre à jour votre ScoDoc: - - cd /opt/scodoc/Products/ScoDoc/config - ./upgrade.sh - - 2. Arrêter le service (en Debian 9 on utilisait *SysV-style init*, à partir de - Debian 10 ScoDoc utilise `systemd`): - - /etc/init.d/scodoc stop - - - 3. Sauvegarder les données et configurations ScoDoc: - - cd /opt/scodoc/Products/ScoDoc/config - ./save_scodoc_data.sh /opt/data-scodoc-deb9 # par exemple - - - 4. Mettre à jour Debian: pour les détails voir - [https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.html](https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.html). - - - En résumé: - - - éditer `/etc/apt/sources.list` et indiquer -``` - deb http://deb.debian.org/debian buster main contrib -``` - - - puis: -``` - apt-get remove firehol - apt update - apt-get upgrade - apt full-upgrade - apt autoremove -``` -et **rebooter**. - - - 5. Supprimer postgresql 9.6 - -On enlève carrément l'ancien, le script d'installation de ScoDoc installera la -version 11: - - apt-get --purge remove postgresql - - - 6. Réinstaller ScoDoc - -Déplacer l'ancienne installation de ScoDoc (vous la supprimerez plus tard): - - mv /opt/scodoc /opt/scodoc.deb9 - - -Réinstaller un ScoDoc tout neuf, en suivant [GuideInstallDebianDix](GuideInstallDebianDix.md) - -La plupart des composants de votre système seront déjà présents, donc répondre en général "non" aux questions du script d'installation. - -S'arrêter avant l'initialisation des bases de données. - - 7. Restaurer la sauvegarde: - - cd /opt/scodoc/Products/ScoDoc/config - ./restore_scodoc_data.sh /opt/data-scodoc-deb9 - -Vérifiez et voilà. - - - Faire un peu de ménage (supprimer `/opt/scodoc.deb9` quand vous êtes sûr de n'y avoir rien oublié), vérifiez les logs (`/opt/scodoc/log`). - - - Vérifier que le nouveau système (et ses bases de données) est bien sauvegardé ([SauvegardesBases](SauvegardesBases.md)). - - diff --git a/docs/ModelisationParcoursBUT.md b/docs/ModelisationParcoursBUT.md new file mode 100644 index 000000000..0ca7fde76 --- /dev/null +++ b/docs/ModelisationParcoursBUT.md @@ -0,0 +1,183 @@ +# Les parcours du BUT dans ScoDoc +Cette documentation est destinée aux développeurs et à tous ceux qui souhaitent +comprendre le fonctionnement du logiciel. + +ScoDoc est livré avec les référentiels de compétences de tous les parcours de toutes +les spécialités de BUT. En effet, ces référentiels sont nationaux, publiés par +le ministère (voir +[https://cache.media.enseignementsup-recherche.gouv.fr/file/SPE4-MESRI-17-6-2021/32/3/_Annexe_1_PN_BUT_version_post_CNESER_20210511_18-05-2021-1_1411323.pdf](https://cache.media.enseignementsup-recherche.gouv.fr/file/SPE4-MESRI-17-6-2021/32/3/_Annexe_1_PN_BUT_version_post_CNESER_20210511_18-05-2021-1_1411323.pdf)) +et ne sont pas susceptibles d'adaptations locales. + +Nous nous sommes basés sur les versions exportées du logiciel Orébut. + +## Rappel général sur le BUT et ScoDoc +Rappel simplifié, se concentrant sur les points utiles pour l'évaluation +et les liens avec le cursus de formation: + + - Chaque parcours de BUT est défini par un ensemble de compétences. + - Une compétence est décomposée en deux ou trois *niveaux*, chacun constitué de + deux UE consécutives (sur semestres pair et impair de la même année + scolaire). + - Les UE sont des UE "LMD" habituelles; associées à des crédits ECTS, + capitalisables. Chaque UE est associée à une note (moyenne d'UE) et une + décision de jury (validée, ajournée, ...). + +Dans le BUT, le référentiel de formation n'est pas fixé nationalement. Une part +est publiée (2/3) par le ministère, le reste est défini localement par les +universités (*adaptation locale*). + +Les modules: on appelle ici "module" tout dispositif pédagogique évalué, dans le +BUT ce sont les *ressources* et les *SAÉ*. + +Dans ScoDoc, le programme pédagogique définit les UE et modules pour l'ensemble +des semestres d'un ou plusieurs parcours. De cette façon, on pourra utiliser les +mêmes éléments dans plusieurs parcours, et grouper les étudiants de plusieurs +parcours dans le même semestre si on le souhaite. + +## Modélisation ScoDoc + +On a d'une part le *programme de formation*, et de l'autre le *référentiel de +compétences*. + +### Programme de formation +Le programme de formation est constitué des classes suivantes (en BUT et dans +tous les types de formation. La notion de "matière" n'est pas utilisée en BUT). + + - Formation (ex: "BUT R&T") + - UniteEns (UE, ex: "Administrer les réseaux") + - Modules (ressources, SAÉs) *<-> ApcAppCritique*, *<-> ApcParcours* + +On voit que les modules ont toujours une UE de rattachement. Cependant, en BUT, +un module peut intervenir dans le calcul des notes de plusieurs UE, via une +matrice de coefficients. + +On va aussi rattacher les Modules à un ou plusieurs ApcParcours, de façon à +pouvoir vérifier que les parcours couvrent les AC, et à faciliter les +inscriptions des étudiants aux modules (par ex. page présentant les modules +auxquels inscrire un groupe). + +### Référentiel de compétences +Le référentiel de compétences est structuré par les classes suivantes: + + - ApcReferentielCompetences + - ApcCompetence + - ApcSituationPro + - ApcComposanteEssentielle + - ApcNiveau (année, ordre) + - ApcAppCritique *<-> Module* + - ApcParcours + - ApcAnneeParcours + - ApcParcoursNiveauCompetence + +Notons le lien entre les apprentissages critiques (ApcAppCritique) et les +modules, qui permet d'établir les critères d'évaluation de chaque module. + +### FormSemestres +La formation est mise en œuvre dans des FormSemestre (date début, fin, +enseignants responsables, ...) constitués de ModuleImpl (module avec enseignant, +évaluations, ...). + + - FormSemestre + - ModuleImpl + - Evaluation + +### Inscriptions des étudiants +Les étudiants sont inscrits: + + - dans un FormSemestre (FormSemestreInscription, avec état (I, D, DEF) et étape + Apogée) + - dans un ModuleImpl (ModuleImplInscription) + - et, pour le BUT, dans un ApcParcours (TODO) + +### Associations (nouvelles pour le BUT): + +Pour la gestion des parcours BUT, il faut introduire les associations suivantes, +qui n'existent pas dans ScoDoc 9.2: + + - Module ||--o{ ApcAppCritique : choix sur la page `module_edit` + - Module <-> ensemble de ApcParcours + - UE <-> ApcParcoursNiveauCompetence : choix sur la page `ue_edit` + - FormSemestre ||--o{ ApcParcours : choix sur la page + `formsemestre_editwithmodules` + - Identite }o--o{ ApcParcours : inscription au parcours, page à créer. + +### Cas d'usage + +#### Inscription d'un étudiant aux ModuleImpls +L'inscription reste libre (chaque individu peut être inscrit à un sous-ensemble +quelconque des ModuleImpl du FormSemestre), mais il sera commode de pouvoir: + + - créer des groupes de parcours + - inscrire les étudiants d'un groupe à tous les modules du parcours. + +#### Comment ScoDoc détermine-t-il les modules d'un parcours ? +Un parcours étant associé à des compétences, et les niveaux compétences à des +UE, on peut déterminer, pour un semestre de rang donné, l'ensemble des UE +associées à un parcours. + +Par ailleurs, chaque niveau de compétence est associé à un ensemble d'AC +(ApcAppCritique), et chaque module est aussi associé à son ensemble d'AC. + +Pour chaque parcours d'un FormSemestre, on déterminera l'ensemble des ModuleImpl +de ce semestre ayant des AC communs avec ceux des niveaux de compétences +associés aux UE du semestre (sic). Notons que les niveaux de compétences sont +annuels, mais que les ModuleImpl sont semestriels. + +#### Vérifier que les ModuleImpls d'un parcours couvrent l'ensemble de ses ACs + +##### En fin de formation, pour un étudiant + +Soit un étudiant inscrit à un parcours. En fin de formation (S6), on peut +facilement vérifier que les AC ont été couverts: + + - Lister les ModuleImpl auxquels l'étudiant a été inscrit dans ses semestres + (S1 à S6); + - En déduire l'ensemble des AC évalués pour cet étudiant (indépendamment de sa + réussite); + - Comparer aux AC du parcours tels que décrits dans le référentiel de compétence. + +##### Au moment de la définition d'une formation + +Le parcours du ref. de compétence indique un ensemble d'AC pour chaque niveau (année). +On pourra vérifier que les Modules de chaque année suffisent à couvrir le +parcours. Mais si les Modules ne sont pas associés à un parcours, on ne peut pas +aller plus loin. + +#### Lister les regroupements d'UE d'un étudiant + +Pour une année donnée: l'étudiant est inscrit dans ScoDoc soit dans le semestre +impair, soit pair, soit les deux (il est rare mais pas impossible d'avoir une +inscription seulement en semestre pair, par exemple suite à un transfert ou un +arrêt temporaire du cursus). + + 1. Déterminer l'*autre* semestre: semestre précédent ou suivant de la même + année, formation compatible (code formation identique ou bien même + référentiel de compétence ?) dans lequel l'étudiant est inscrit. + + 2. Construire les couples d'UE (regroupements cohérent): apparier les UE qui + ont le même ApcParcoursNiveauCompetence. + +#### Déterminer si un étudiant peut passer dans l'année suivante + +Note: on peut bien sûr toujours forcer le passage, pour traiter les cas +particuliers (décision de jury manuelle). + +**Rappel:** le passage est de droit si + + - [x] plus de la moitié des niveaux de compétences de l'année sont validés + - [x] aucun regroupement d'UE (niveau de compétence) de l'année < 8 /20 + - [x] pour le passage en S5, avoir validé toutes les UE du BUT 1 (S1 et S2). + +Il faut donc: + 1. Construire les regroupements d'UE et calculer la moyenne des moyennes d'UE + (a priori de même poids, cela n'est pas spécifié dans les textes). + + 2. Vérifier les conditions ci-dessus. + + 3. Pour le passage en S5, construire l'ensemble des semestres de formations + relevant du même référentiel de compétences dans lesquels a été inscrit + l'étudiant, et vérifier que les UE de S1 et S2 sont validées. + + + + diff --git a/docs/ModulesMalus.md b/docs/ModulesMalus.md index 25f0fe458..827898372 100644 --- a/docs/ModulesMalus.md +++ b/docs/ModulesMalus.md @@ -9,4 +9,3 @@ Lors de la création d'un module dans un programme pédagogique, on peut spécif Une fois le module créé (et ajouté à un semestre), on peut y déclarer une évaluation et saisir les notes de bonus/malus. Ces notes sont toujours *à prise en compte immédiate*, il n'est donc pas nécessaire de saisir des notes de malus pour tous les étudiants. - diff --git a/docs/ParametrageBulletins.md b/docs/ParametrageBulletins.md index 2c1f51439..c9f10e11b 100644 --- a/docs/ParametrageBulletins.md +++ b/docs/ParametrageBulletins.md @@ -31,7 +31,6 @@ Toutes les préférences pour le semestre considéré (ou définies globalement) Voir la liste complète sur [NomsPreferences](NomsPreferences.md). - ### Informations sur le semestre Variable | Valeur ---------|------- @@ -61,7 +60,7 @@ descr_demission || "Démission le 01/02/2000" ou vide si pas de démissio decision_jury || "Validé", "Ajourné", ... (code semestre descr_decision_jury| "Décision jury: Validé" (une phrase decisions_ue || noms (acronymes) des UE validées, séparées par des virgules. -descr_decisions_ue|| " UE acquises: UE1, UE2", ou vide si pas de dec. ou paramètrage +descr_decisions_ue|| " UE acquises: UE1, UE2", ou vide si pas de dec. ou paramétrage mention| Mention, calculée d'après la moyenne générale | **Absences:** | @@ -96,16 +95,19 @@ Le balisage XML est celui de [ReportLab](http://www.reportlab.com/) (intra-parag ### Logos Une balise supplémentaire est interprétée par ScoDoc pour insérer des logos (images). -Les logos sont des images au format JPEG (extension `.jpg` ou `.jpeg`) ou PNG (expension `.png`), téléversés sur le serveur scodoc et intégrables dans les documents html ou pdf. +Les logos sont des images au format JPEG (extension `.jpg` ou `.jpeg`) ou PNG +(extension `.png`), téléversés sur le serveur scodoc et intégrables dans les +documents PDF. [Plus d'information sur la gestion des logos ici](GestionLogos.md). Principes généraux : * Un logo est désigné par un identifiant (nom) et peut être défini soit globalement, soit pour un département; -* le nom d'un logo est exclusiement composé de caractères alphanumériques ou du caractère '`-`'; +* le nom d'un logo est exclusivement composé de caractères alphanumériques ou du caractère '`-`'; -* les logos définis globalement sont accessibles pour tous les départements. Toutefois, si un logo de même nom est également présent dans un département, -, c'est le logo du département qui sera utilisé en lieu et place de logo global; +* les logos définis globalement sont accessibles pour tous les départements. +Toutefois, si un logo de même nom est également présent dans un département, +c'est le logo du département qui sera utilisé en lieu et place de logo global; * les logos de nom '`header`' et '`footer`' définis globalement ne peuvent être supprimés (mais peuvent être redéfinis). @@ -116,7 +118,7 @@ Ce formulaire comporte une section pour les définitions globales plus une secti Une section présente la liste des logos avec leurs propriétés (la dimension est donnée à titre indicatif quand elle est disponible). -Pour chaque logo, les actions diponibles sont : +Pour chaque logo, les actions disponibles sont : * Le remplacement de l'image existante par un nouveau fichier ; @@ -134,6 +136,9 @@ Notez qu'il est possible de ne préciser que l'une des deux dimensions hauteur o Dans ce cas, la dimension manquante est déduite du ratio (rapport hauteur/largeur) de l'image originale. Voir un exemple d'utilisation plus bas. +### Fond de page. +Les modalités d'utilisation des fonds de pages sont similaires pour les PV, les lettres individuelles de décision et les bulletins. +Celles-ci sont décrites ici: [Paramétrage des PV. Images de fond de page](ParametragePV.md) ## Exemples ### Exemple 1: Bulletins par défaut diff --git a/docs/ParametragePV.md b/docs/ParametragePV.md index 6b5319136..d4beba581 100644 --- a/docs/ParametragePV.md +++ b/docs/ParametragePV.md @@ -10,14 +10,32 @@ Le PV de jury est en format paysage et liste les résultats des étudiants chois ## Image de fond de page (logos, tête, pied) L'exemple ci-dessus utilise une image de fond qui contient l'en-tête et le pied de page, avec des logos. Il faut fournir à ScoDoc une image de fond. Le plus simple est généralement de la composer dans un logiciel de traitement de texte, et de l'enregistrer en image: exporter en PDF puis convertir le PDF en image PNG ou JPEG de bonne résolution (300dpi , par exemple avec un logiciel comme Aperçu sur Mac. -L'image doit ensuite être enregistrée sur le serveur à un emplacement spécifique (seul l'administrateur du serveur peut faire cela): +L'image obtenue peut ensuite être téléversée sur le serveur de la même façon que pour un simple logo +(voir la section [paramétrage des bulletins, section Logos](ParametrageBulletins.md) +avec le nom "`pvjury_background`" ou "`letter_background`" selon le type de document visé. - - Pour les PV de jury (A4 paysage), sous le chemin `/opt/scodoc/var/scodoc/config/logos/pvjury_background.png` - - Pour les lettres individuelles (format A4 portrait), sous `/opt/scodoc/var/scodoc/config/logos/letter_background.png` +Il ne reste plus qu'à activer l'option correspondante soit globalement dans le +paramétrage du département, soit (pour les bulletins) dans par le menu réglage +bulletin du semestre (qui a priorité): -Ne pas oublier d'activer l'option *"Mettre l'image de fond sur les PV de jury"* dans les [paramètres du département](PreferencesScoDoc.md). + - Mettre l'image de fond sur les PV de jury (paysage) + - Mettre l'image de fond sur les bulletins + - Mettre l'image de fond sur les lettres individuelles de décision -**Note :** on peut aussi ajouter les logos séparément, mais il est plus commode de fournir une trame de fond complète. Voir [ici](GuideConfig/#changement-des-logos-apparaissant-sur-les-documents) si besoin. +**Note** : pour les serveurs migrés depuis ScoDoc 7, les anciennes +configurations sont normalement reprises automatiquement. + +L'image doit ensuite être enregistrée sur le serveur à un emplacement spécifique +(seul l'administrateur du serveur peut faire cela): [voir la page sur la +configuration les images](GestionLogos.md). + +Ne pas oublier d'activer l'option *"Mettre l'image de fond sur les PV de jury"* +dans les [paramètres du département](PreferencesScoDoc.md). + +**Note :** on peut aussi ajouter les logos séparément, mais il est souvent plus +commode de fournir une trame de fond complète. Voir +[ici](GuideConfig/#changement-des-logos-apparaissant-sur-les-documents) si +besoin. ## PV de Jury: textes, marges et autres paramètres @@ -31,9 +49,11 @@ Les paragraphes de texte utilisent un balisage identique à celui des bulletins ## Lettres individuelles -ScoDoc génère un docuement PDF contenant les letters de tous les étudiants du semestre ou d'un groupe. +ScoDoc génère un document PDF contenant les lettres de tous les étudiants du semestre ou d'un groupe. -Le principe est le même, mais on fournit une trame de fond au format portrait, come indiqué plus haut. Le texte de la lettre est configurable dans les préférences. +Le principe est le même, mais on fournit une trame de fond au format portrait, +comme indiqué plus haut. Le texte de la lettre est configurable dans les +préférences. diff --git a/docs/SauvegardesBases.md b/docs/SauvegardesBases.md index 883ba682e..4b8af2c2d 100644 --- a/docs/SauvegardesBases.md +++ b/docs/SauvegardesBases.md @@ -55,10 +55,17 @@ et ajouter: ## En cas de problème: restaurer la base à partir d'une sauvegarde -/!\ Attention, certaines informations sont stockées dans des fichiers et non dans la base de données: configuration du logiciel, photos des étudiants. Ce paragraphe ne traite que de la restauration à de la base de données. + Attention, certaines informations sont stockées dans des fichiers +et non dans la base de données: configuration du logiciel, photos des étudiants. +Ce paragraphe ne traite que de la restauration de la base de données. + +Rappel: en ScoDoc 9, il n'y a qu'une seule base de donnée SQL, nommée par défaut +`SCODOC`. Cette base contient les données des départements et la définition des +comptes utilisateurs. 1. Choisir la sauvegarde à utiliser, en fonction de la date à partir de - laquelle on a fait une erreur (eg suppression non intentionnelle d'un + laquelle on a fait une erreur (par ex. suppression non intentionnelle d'un semestre...). Le fichier se trouve sous `/var/lib/postgresql/SCODOC-BACKUPS`où `XXX` est concerné. Utiliser par exemple `ls -lrt` pour visualiser les sauvegardes triées par date. @@ -76,24 +83,18 @@ et ajouter: ``` # en tant que root... systemctl stop scodoc9 # arret du serveur -su postgres -dropdb SCODOC # <<< votre base production -pg_restore -C -d scodoc /tmp/XXX # (nom de la BDD en majuscule) +su - scodoc +dropdb SCODOC # <<< votre base production +createdb -E UTF-8 SCODOC +pg_restore -d SCODOC /tmp/SCODOC_pgdump.gz # (nom du fichier dump) +source venv/bin/activate +flask db upgrade # nécessaire seulement si sauvegarde ancienne +flask clear-cache + exit # retour a l'utilisateur root systemctl start scodoc9 # relance ScoDoc ``` -Attention: s'il y a eu des mise à jour du logiciel entre temps, il peut arriver -que la base sauvegardée nécessite une migration. Arrêtez le service scodoc9, -puis, en tant qu'utilisateur `scodoc`, lancer les commandes suivantes: - - cd /opt/scodoc - source venv/bin/activate - flask db upgrade - -puis relancer le service (`systemctl start scodoc9` comme root). - - ## Déplacement de toute une installation Les scripts ci-dessus ne se chargent que de la base de données SQL. diff --git a/docs/ScoDoc9API.md b/docs/ScoDoc9API.md index 892cba59b..e0b82395c 100644 --- a/docs/ScoDoc9API.md +++ b/docs/ScoDoc9API.md @@ -1,5 +1,5 @@ -# API pour ScoDoc 9 +## API pour ScoDoc 9 L'API ScoDoc permet à des applications tierces d'interroger ScoDoc. Elle offre un accès aux informations aux formats XML et JSON. La version ScoDoc 9 a introduit une nouvelle API avec un nouveau mécanisme d'authentification. @@ -24,45 +24,51 @@ Les objets ScoDoc manipulables sont identifiés par des id. L'URL complète est de la forme: `https://scodoc.example.com/ScoDoc/api/fonction`. -# Fonctions de l'API ScoDoc 7 portées en ScoDoc 9 +## Configuration de ScoDoc pour utiliser l'API -L'ancienne API ScoDoc 7 est décrite ici: [ScoDocAPI](ScoDocAPI.md) +Il est nécessaire de disposer d'un compte utilisateur avec les droits adéquats. -Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les -fonctions suivantes sont disponibles avec le mécanisme d'authentification -basique de ScoDoc 7. Elles sont considérées comme *obsolètes* ("deprecated") et -disparaitront en juillet 2022. +En général, il est recommandé de créer un rôle, de lui attribuer les permissions +que l'on veut utiliser, puis de créer un utilisateur ayant ce rôle. -Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès. +En ligne de commande, cela peut se faire comme suit (voir détail des commandes +[sur le guide de configuration](GuideConfig.md)). - - `Absences/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/ etudid>`) - - `Absences/AddBilletAbsence` (deviendra `api/absences/billet/add`) - - `Absences/XMLgetAbsEtud` (deviendra `api/absences/ etudid>`, en json) - - `Notes/evaluation_listenotes` (non existante en ScoDoc9, trop complexe) - - `Notes/formsemestre_id` (deviendra `api/formsemestre`) - - `Notes/formsemestre_bulletinetud` (deviendra `api/etud//bul/`) - - `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?) - - `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/`) - - `groups_view` (deviendra `groups`) +``` +# se connecter comme utilisateur scodoc +su - scodoc -Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est -à dire `https://votre.site.fr/ScoDoc//Scolarite/`, et répondent en GET et -en POST. +# Créer un rôle +flask create-role LecteurAPI +# Lui donner les droits nécessaires: ici APIView +flask edit-role LecteurAPI -a APIView -Note: - - `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API. +# Créer un nouvel utilisateur avec ce rôle: +flask user-create lecteur_api LecteurAPI @all -# Fonctions d'API ScoDoc 9 (work in progress) +# Ou bien, si on veut utiliser un compte existant: +# associer notre rôle à un utilisateur +flask user-role lecteur_api -a LecteurAPI + + +# Au besoin, changer le mot de passe de l'utilisateur +# (on aura besoin de ce mot de passe dans la configuration du client d'API) +flask user-password lecteur_api +... +``` + +## Fonctions d'API ScoDoc 9 (work in progress) Basé sur le ticket [#149](https://scodoc.org/git/viennet/ScoDoc/issues/149) -La documentation ci-dessous concerne la **future** version De ScoDoc. +La documentation ci-dessous concerne la **future** version de ScoDoc (9.3, avec +parties expérimentales progressivement mises en production à partir de 9.2.12). -## Accès à l'API REST +### Accès à l'API REST Elle sera accessible à l'adresse: https://scodoc.monsite.tld/ScoDoc/api/fonction -### Authentification +#### Authentification Lors de votre authentification (_connection avec login et mdp_) à Scodoc, il vous sera attribué un jeton (token jwt _généré automatiquement_) vous permettant @@ -87,7 +93,7 @@ La réponse doit ressembler à ceci: Vous trouverez dans `/opt/scodoc/tests/api/exemple-api-basic.py` un exemple complet en python d'interrogation de l'API. -### Codes HTTP +#### Codes HTTP Chaque appel à l'API donne lieu à une réponse retournant un code spécifique en fonction du résultat obtenu. L'analyse de ce code vous permet de vous assurer que la requête a été traitée avec succès. @@ -105,7 +111,7 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * [503](https://developer.mozilla.org/fr/docs/Web/HTTP/Status/503) : L'API est momentanément indisponible, réessayez dans quelques minutes. -## Départements +### Départements * **`departements`** * **Méthode:** GET * **Paramètres:** `viewable` (optionnel, si faux liste aussi les @@ -117,15 +123,16 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **Exemple de résultat:** `[id_1, id_2, id_3, ...]` - * **`liste_etudiants`** + * **`etudiants`** XXX à revoir * **Méthode:** GET * **Paramètres:** `dept`, `semestre` - * **Routes:** `/api/departements//etudiants/liste/` (_`semestre` étant un paramètre optionnel_) + * **Routes:** `/api/departements//etudiants/liste/` * **Exemple d'utilisation:** `/api/departements/MMI/etudiants/liste` - * **Résultat:** liste des étudiants d'un département - semestre actuel par défaut. + * **Résultat:** liste des étudiants d'un département - semestre actuel par + défaut. XXX à préciser - * **`liste_semestres_actifs`** + * **`liste_semestres_actifs`** XXX à revoir * **Méthode:** GET * **Paramètres:** `dept` * **Routes:** `/api/departements//semestres_actifs` @@ -133,15 +140,15 @@ Tous les codes >= 400 indiquent que la requête n'a pas été traitée avec succ * **Résultat:** Liste des semestres actifs d'un département donné. (_réponse sous format json_) - * **`referenciel_competences`** + * **`referentiel_competences`** * **Méthode:** GET - * **Paramètres:** `dept`, `formation` (_`formation` étant un id de formation, un programme pédagogique_) - * **Routes:** `/api/departements//formations//referentiel_competences` - * **Exemple d'utilisation:** `/api/departements/MMI/formations/12/referentiel_competences` - * **Résultat:** Le référentiel de compétences d'une formation donnée. (_pas toujours présent_) + * **Paramètres:** `id`, id du référentiel + * **Routes:** `/api/referentiel_competences/` + * **Résultat:** Le référentiel de compétences d'une formation donnée (json). (_pas toujours présent_) + * XXX obtenir la liste des référentiels -## Etudiants +### Etudiants * **`etud_dept`** * **Méthode:** GET * **Paramètres:** `code_nip` @@ -451,7 +458,7 @@ formsemestre_id": "SEM12345", } ``` -## UE +### UE * **`UEs`** * **Méthode:** GET * **Paramètres:** `dept`, `̀semestre` @@ -462,7 +469,7 @@ formsemestre_id": "SEM12345", -## Semestres de formation +### Semestres de formation Les sessions de formation (dénommées "semestres" même si elles durent une année ou un mois) sont représentées par les `formsemestre`. * **`formsemestre`** @@ -492,7 +499,7 @@ Les sessions de formation (dénommées "semestres" même si elles durent une ann ] ``` -### Note sur les identifiants de sessions +#### Note sur les identifiants de sessions Le `session_id` peut être utilisé pour identifier de façon prévisible et (presque) unique une session dans un établissement, ce qui est utile notamment pour interfacer ScoDoc à d'autres logiciels (par exemple gestion d'emplois @@ -513,7 +520,7 @@ informations suivantes: **Exemple:** `INFO-DUT-FI-S1-2014` équivaut à un semestre S1 d'un DUT informatique de 2014 en formation initiale (FI) -## Modules de formation +### Modules de formation Les moduleimpl sont les modules d'un semestre, ou les ressources, ou les SAÉs. On peut récupérer soit un module par son id, soit la listes des modules d'un semestre. @@ -529,7 +536,7 @@ On peut récupérer soit un module par son id, soit la listes des modules d'un s -## Groupes et partitions +### Groupes et partitions L'ensemble des étudiants d'un semestre peut être réparti selon une ou plusieurs partitions (types de groupes). Chaque partition est constituée @@ -663,7 +670,7 @@ d'un nombre quelconque de groupes d'étudiants. TODO: à changer, passer les paramètres dans le corps de la requête -## Bulletins de notes +### Bulletins de notes * **`evaluations`** * **Méthode:** GET * **Paramètres:** `moduleimpl_id` @@ -701,7 +708,7 @@ d'un nombre quelconque de groupes d'étudiants. TODO vérifier et passer les valeurs dans le corps. -## Absences +### Absences **Remarques**, les dates sont au format iso `yyyy-mm-dd`. Les dates de fin ne sont pas incluses. Et `demi_journee`= 2 si journée complète, =1 si uniquement le matin, =0 si uniquement l'après-midi. @@ -761,7 +768,7 @@ d'un nombre quelconque de groupes d'étudiants. ] ``` -## Logos +### Logos * **`liste des logos globaux`** * **Méthode:** GET @@ -797,6 +804,33 @@ d'un nombre quelconque de groupes d'étudiants. * **Résultat :** l'image (format png ou jpg) +### En savoir plus +Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. -## En savoir plus -Voir exemples d'utilisation de l'API en Python, dans `tests/api/`. \ No newline at end of file +## Fonctions de l'API ScoDoc 7 portées en ScoDoc 9 + +L'ancienne API ScoDoc 7 est décrite ici: [ScoDocAPI](ScoDocAPI.md) + +Afin de garantir l'interopérabilité avec les clients ScoDoc 7 (ENT, etc), les +fonctions suivantes sont disponibles avec le mécanisme d'authentification +basique de ScoDoc 7. Elles sont considérées comme *obsolètes* ("deprecated") et +disparaitront en juillet 2022. + +Certaines ont plusieurs "routes" (URl), car ScoDoc 7 tolérait divers accès. + + - `Absences/XMLgetBilletsEtud` (deviendra `api/absences/billets/etud/ etudid>`) + - `Absences/AddBilletAbsence` (deviendra `api/absences/billet/add`) + - `Absences/XMLgetAbsEtud` (deviendra `api/absences/ etudid>`, en json) + - `Notes/evaluation_listenotes` (non existante en ScoDoc9, trop complexe) + - `Notes/formsemestre_id` (deviendra `api/formsemestre`) + - `Notes/formsemestre_bulletinetud` (deviendra `api/etud//bul/`) + - `Notes/XMLgetFormsemestres` (non existante en ScoDoc9, redondant avec `api/formsemestre` ?) + - `etud_info` ou `XMLgetEtudInfos` ou `Absences/XMLgetEtudInfos` ou `Notes/XMLgetEtudInfos` (deviendra `/api/etud/`) + - `groups_view` (deviendra `groups`) + +Les routes ci-dessus s'entendent à partir de l'URL de base de votre ScoDoc, c'est +à dire `https://votre.site.fr/ScoDoc//Scolarite/`, et répondent en GET et +en POST. + +Note: + - `Absences/listeBillets` est un formulaire et ne fait pas partie de l'API. diff --git a/docs/assets/grenouille_bleue.png b/docs/assets/grenouille_bleue.png new file mode 100644 index 000000000..06746f952 Binary files /dev/null and b/docs/assets/grenouille_bleue.png differ diff --git a/docs/assets/images/android-chrome-192x192.png b/docs/assets/images/android-chrome-192x192.png new file mode 100755 index 000000000..24b79905f Binary files /dev/null and b/docs/assets/images/android-chrome-192x192.png differ diff --git a/docs/assets/images/android-chrome-512x512.png b/docs/assets/images/android-chrome-512x512.png new file mode 100755 index 000000000..df7b68d00 Binary files /dev/null and b/docs/assets/images/android-chrome-512x512.png differ diff --git a/docs/assets/images/apple-touch-icon.png b/docs/assets/images/apple-touch-icon.png new file mode 100755 index 000000000..9d50ea8ce Binary files /dev/null and b/docs/assets/images/apple-touch-icon.png differ diff --git a/docs/assets/images/favicon-16x16.png b/docs/assets/images/favicon-16x16.png new file mode 100755 index 000000000..da06df161 Binary files /dev/null and b/docs/assets/images/favicon-16x16.png differ diff --git a/docs/assets/images/favicon-32x32.png b/docs/assets/images/favicon-32x32.png new file mode 100755 index 000000000..46e39ffcc Binary files /dev/null and b/docs/assets/images/favicon-32x32.png differ diff --git a/docs/assets/images/favicon.png b/docs/assets/images/favicon.png new file mode 100755 index 000000000..46e39ffcc Binary files /dev/null and b/docs/assets/images/favicon.png differ diff --git a/docs/fig/GrapheUser.odg b/docs/fig/GrapheUser.odg new file mode 100644 index 000000000..8bf9a57c3 Binary files /dev/null and b/docs/fig/GrapheUser.odg differ diff --git a/docs/fig/GrapheUser.png b/docs/fig/GrapheUser.png new file mode 100644 index 000000000..f1c2d81f6 Binary files /dev/null and b/docs/fig/GrapheUser.png differ diff --git a/docs/index.md b/docs/index.md index 9898d5e8a..6238de249 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,14 +1,19 @@ # ScoDoc: un logiciel libre pour le suivi de la scolarité -ScoDoc est un logiciel libre créé par Emmanuel Viennet pour suivre la scolarité des étudiants universitaires. Il est principalement utilisé dans les IUT, mais aussi apprécié par plusieurs Écoles et Masters en France et à l'étranger. Il fournit notamment: +ScoDoc est un logiciel libre créé par Emmanuel Viennet pour suivre la scolarité +des étudiants universitaires. Il est principalement utilisé dans les IUT, mais +aussi apprécié par plusieurs Écoles et Masters en France et à l'étranger. Il +fournit notamment: - - suivi précis de la progression des étudiants, évaluations formatives et certificatives; + - suivi précis de la progression des étudiants, évaluations formatives et + certificatives - saisie et gestion des notes; - aide à la décision pour les jurys; - listes des étudiants (groupes, trombinoscopes, bordereaux divers); - suivi de l'assiduité (saisie et visualisation des absences); - - tableaux de bords, rapports statistiques sur la formation (suivis de cohortes, ...) utiles pour l'évaluation et le suivi des formations; + - tableaux de bords, rapports statistiques sur la formation (suivis de + cohortes, ...) utiles pour l'évaluation et le suivi des formations; - édition des procès-verbaux, bulletins et autres documents liés à la scolarité. @@ -17,11 +22,17 @@ ScoDoc est un *logiciel libre*: vous pouvez [participer à son développement](C ScoDoc s'utilise sur un navigateur web standard: les utilisateurs n'ont rien à installer. Les établissements ou écoles doivent configurer un serveur: voir le [guide d'installation sur Debian 11](GuideInstallDebian11.md). La version ScoDoc 9 est -parue le 19 septembre 2021. +parue le 19 septembre 2021, la version 9.2 en avril 2022. Les mises à jour sont +appliquées régulièrement. -ScoDoc est utilisé dans de nombreux établissement français et étrangers, **dont au moins 58 IUT**: [liste des utilisateurs connus de ScoDoc](UtilisateursScoDoc.md). +ScoDoc est utilisé dans de nombreux établissement français et étrangers, **dont +au moins 58 IUT**: [liste des utilisateurs connus de +ScoDoc](UtilisateursScoDoc.md). -Depuis 2020, ScoDoc est soutenu par une [association à but non lucratif (1901)](AssociationScoDoc.md), à laquelle tous les départements ou établissements utilisateurs sont **invités à adhérer**. Bulletin d'adhésion à retourner à `Emmanuel.Viennet at gmail.com`. +Depuis 2020, ScoDoc est soutenu par une [association à but non lucratif +(1901)](AssociationScoDoc.md), à laquelle tous les départements ou +établissements utilisateurs sont **invités à adhérer**. Bulletin d'adhésion à +retourner à `Emmanuel.Viennet at gmail.com`. ## Présentation générale @@ -29,27 +40,37 @@ Depuis 2020, ScoDoc est soutenu par une [association à but non lucratif (1901)] - Quelques vidéos d'introduction sur YouTube - - Présentation au colloque du [CRI-IUT](https://www.criiut.fr/) en 2013: [diapos en pdf](papers/presScoDocCRIIUT2013.pdf) + - Ancienne présentation au colloque du [CRI-IUT](https://www.criiut.fr/) en 2013: [diapos en pdf](papers/presScoDocCRIIUT2013.pdf) - Un très ancien [article sur ScoDoc](papers/scodoc-reunion2007.pdf) ## Communauté d'utilisateurs - - Le discord des utilisateurs: assistance chat ou audio [rejoindre le salon](https://discord.gg/ybw6ugtFsZ) + - Le Discord des utilisateurs: assistance chat ou audio [rejoindre le salon](https://discord.gg/ybw6ugtFsZ) - [Listes de diffusion e-mail](ListesDeDiffusion.md) - Vous pouvez signaler ici des bugs ou déposer des suggestions d'amélioration via les "tickets": * [Liste des tickets en cours](https://scodoc.org/git/viennet/ScoDoc/issues) - * Déclarer un nouveau ticket: demander un compte sur la liste scodoc-devel (lien ci-dessus). + * Déclarer un nouveau ticket: demander un compte sur la liste `scodoc-devel` (lien ci-dessus). - [Contribuer à ScoDoc](Contribuer.md) ## Actualités -### Parution de ScoDoc 9.0 -Version majeure, avec une architecture logicielle complètement remaniée. Dans un -premier temps, ScoDoc 9 n'offre presque pas de nouvelles fonctions par rapport à -l'ancien ScoDoc 7, mais son code permet des évolutions plus aisées. +### Parution de ScoDoc 9 +Version majeure, avec une architecture logicielle complètement remaniée. Cette +version modernise l'infrastructure logicielle (maintenant basée sur Python +3/Flask/postgresql) et propose de nombreuses améliorations, notamment pour la +gestion du *[Bachelor Universitaire de Technologie (BUT)](BUT.md)*. -### Quatre stagiaires (printemps 2021) +### Contrats d'apprentissage + +Deux étudiants ont été recrutés (LP IUT Orléans, et IUT Villetaneuse): + + - développement d'une nouvelle API pour ScoDoc 9; + - développement d'un nouveau module de gestion des relations entreprises + (fichier, contacts, stages, alternance). + + +### Quatre stagiaires - version spéciale pour mobiles, développée par un stagiaire de l'association; - développements de tests unitaires et fonctionnels, par deux stagiaires, l'un @@ -82,8 +103,19 @@ entente. ### Feuille de route (roadmap) Les prochaines versions de ScoDoc (*sous réserve !*): - - ScoDoc 9.0 : publiée le 19 sept. 2021, version complètement remaniée en - Python 3/Flask. + + - ScoDoc 9.3 : prévue en mai 2022 + - tenue des jurys BUT et exports Apogée + - gestion des parcours (pour la mise en place des semestre) + + + - ScoDoc 9.2 : publiée en avril 2022 nouvelles fonctionnalités liées au BUT + - référentiels de compétences Orébut + - capitalisation des UE dans le BUT + - bonus/malus locaux + - bulletins BUT pdf + - nouveau module de gestion relations avec les entreprises + - ScoDoc 9.1 : décembre 2021 gestion du bachelor (BUT) - type de formation BUT @@ -94,10 +126,9 @@ Les prochaines versions de ScoDoc (*sous réserve !*): - calcul des moyennes d'UE - bulletin de note v1 - - ScoDoc 9.2 : fin 2021 ou début 2022 nouvelles fonctionnalités liées au BUT - - tenue des jurys de S1 - - gestion des parcours (pour la mise en place des semestre) - - import Orébut avec gestion adaptation locale (à l'étude) + - ScoDoc 9.0 : publiée le 19 sept. 2021, version complètement remaniée en + Python 3/Flask. +
diff --git a/docs/misc/scodoc-repo.gpg.key b/docs/misc/scodoc-repo.gpg.key new file mode 100644 index 000000000..c611aa1a8 --- /dev/null +++ b/docs/misc/scodoc-repo.gpg.key @@ -0,0 +1,51 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- + +mQINBGEkuIUBEAClK699yEifRP0TOVpslbEguSt59VMtTg8AYroPX5lalyB/ccdo +Z3hhFuzwTIQ/V7NG8P9OzFud/rKCH6gJLwlXum3a4/pHyg3Qj2naZsIRKEsy7SWp +YUmFS5MKWAynPVbUK1CuIdw1aU9/ENTL98FMBfDKA2l2vkFdDvYGDtZhJ243d1pW +7wq0nDuDCeNSh7QHS+sI9hNQ3loeIxGzvZD/89wTDJp5ihdcaw1tvU4EaCEqgAu2 +hZ3luGsxsFcTqlbk0U26rWZlfDNhtHSmwtPobsHLD5p6OhjFgOhOiOJUe0Hp9VjQ +0Dkt6fyIxfU2UPZMEHhCByFsgHx2gfAZbi1orH6rmR0byVAJVbF58GEUXnuxNayq +sR1Bi+elWIoGxjs98Un4ho+LqBhZr0nSEqovYDMp9AgX8Rx+oAn8CB6EkDUHI8b6 +BOrZFyGUt9UUQiIk7KkAH0VqdNxFtfqrwE1c1sc9RkEJcjxkLNaFPPyJKmpgtJfe +H4m2pX7EZH8NkvYhIMMRxSm5Jja6is2nJS+BLrLGiAjjYvGCqYq6Eurmjc+h6KKW +nLORHJCVkXwOYjJtX81fwos5cAcOmKz/QwoZPWU3QWvGq/KoAiTnFoQMwoagnVOA +55XhTLa1+V/3KpyrQupee4Uctj4doLeipZRuRXPcM/6A3z/XOMrucD6oUwARAQAB +tCdFbW1hbnVlbCBWaWVubmV0IDxlbW1hbnVlbEB2aWVubmV0Lm5ldD6JAjgEEwEI +ACIFAmEkuIUCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJEDm3l8G72kz3 +Y2wP/R3lu/wYsIiO17ISbQfJyBSOArs/Rkbl+Y01p35Hb1HvQ4rmJHkPt/+NuIZk +iu0mR5B9f/3RRFZYvqraVWSXtbuputIXaClRiMRsk/xYfa+u5E+vFTcG/uM7yifF +rNT7zdr/064MDXewhAN6YZsaCJHOHL+Ga+vtc3NwDHdqPDAon4P6j4eDlZQ4heZ2 +7DTXDiVsyqbf1UTSgDSmGyfNI6kCHh9LTYxnT3k3G5sKrGwqtfYOij3o35M3CvB4 +e3YP2UFjCf33ymRgzJz/INiLMeJAMtGb1f0F0LeLNaeCrmUSS2/BZTNVE6h2CcR4 +hGvWQKZSedvVaP2oZ34WxlcxDkwi84bVMX5W4lKxu26D2KjbPJhrgoVf7pt1yNKd +FeqsmP7r9uE5W/C/WdDxb6vvW4GN6gK8SzBz/iIAW3JPfxL4EUuRT8XMgkaaojZd +yWaxk9N2t08joWUnK7eI2LPX9zYNO2EZbPmXOoQyUH7O7KMMAvEQkWvIUtO3GERG +FeLktW6yI9UZ8tQ2H8IgPU0k+YoABJBnRy4PbfnzCTlza+E93VyyFgk5ZltdYHTP +jfSVx2GrWVGrURGMKrOIeDCgSDhrQzow3uj7AUtqLOP5zJM2nL131dJ4lNkeh7VL +banmZvZofhJFK0gAzhuJd0JTul3vesoVS8/frm9OfwI+kIRruQINBGEkuIUBEACz +USdULoaXJXB1LKsLM+6lXzywHWzgmA3B2aiikAsooedc1n7y/xR20FFpHkieDQbK +xUNPSF75dxrfLMMuG4QQYo+r1G3ujHgBrw6IfytP8h0fmPhIaZOYzlEKWF47eeOZ +18FBAMGRX+hA72cv/mARDlmPVh7K4Rdl9FAIANBuEftU70i0eNPKj+CBJ8/qE4JV +iCEvG3hfrmCI+Oe8dlJliKBVVW5L0oMLF777GLvHUuFdKG51TNRIeRcrz7F8/Aax +9CuY3SY5jezVGeDxH/ZiVZua5Y8b9kh8qDuQuAdGj7q9uQU6vNJ9BhfGD2ZUUX1V +/KmMBkv3nDg5Bkk9Puf+E2jc09mQkcOhuo3hSYmD1AWH/JFs+W6fYKVEMPinLGUC +v4l225Jdtu9Ah8N+SxsRrkg/tDuvXM1eka/Xyy/ppXmst8zodPLSDv3uGUvd4rmk +GKs047CZbfbiqd7OrqIHkdxGX50MzPoJ46eq5tKKwyZ24WgXW0MJ/2ML6iGVGsr5 +0QK8JMMYpTYuDMgvfuo8P7LSqxVZ1wdyltCyDDqiE6TBPkvjTIE89f4BpAj54H4l ++h26tFisVR+Qmu1CAVvqFR1N7UD6s17K2GYcyQauDJpViMVRTla+I5aB6c3rJdZ4 +MYLNxzbinD48nxlU6CiBrCQ3rU7HHGHUCsoGA4UK0QARAQABiQIfBBgBCAAJBQJh +JLiFAhsMAAoJEDm3l8G72kz38lAP/3GEKlJs1HYvMQ/UrZrORS+ykuEVaSmVQBVD +zONYzlgxgyYEFpdIf90+QEORk32KySV+2MnSnL5jeaAbFlBS8KQ2u7ldlA68esuo +T4HdNTLOa+XCDTF8AJzr7tmulPiU5k2EhUfYGdU5vOufF1wUc5vqqSWaoy+EXSc/ +kymLObC7R/Bgr6rXEaXwIpxZQTmodUmQgHaVDL3PPABhEs8QD/pm3OM2Qk26+4+/ +ICc+O0qmM59wbH73cmWP1CGKRrqp6l++oDG3I+LnxioGJ+uqcxH4FdSy3fqh30q3 +RTFgknBRZKDmGOjvNiOrExXhM9MornNQ8bJQZGehuVi8iWmq1bgcJbFaFiCzYyL3 +1dvhuMA4ql65KrgcCciJE3jCo0Lq5xXCEm/zhA/WNnYLOwBM+2au3QmyFlRjSJIf +9KFkpUG0psS6NI9DvnyaZrrvhz6sdspap7SY93Vllweg7yRYlI+vsTaxDjqs+WlN ++LSHZnC57Gssl9jwq6WBm7VlAoJZ2sipTqrwlYbD4VdcaMd9C8pLCsVa5etJKwlr +Pdg5l37Os2zgsP00NieX1P4HHmGzV1j1TsYrzaiCJ5g35h/lIqQV7z6ndvPX2TD2 +eokuBieXFuxRPlscA+Diudyvl6jJ1ATJI48GUpcUg2sC7iM91IsG4tC9GGOrmAqV +LwbpXjdu +=MuGd +-----END PGP PUBLIC KEY BLOCK----- diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 000000000..fd7da62b7 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,28 @@ +div.md-sidebar--secondary, +div.md-sidebar--secondary div { + background-color: rgb(217, 217, 217); + border-radius: 8px; +} + +div.md-sidebar--secondary div.md-sidebar__scrollwrap { + margin-left: 0; + margin-right: 0; +} + +.md-content h1, +.md-content h2, +.md-content h3 { + margin-block-start: 0px; + margin-top: 0px; + margin-bottom: 0px; + font-weight: bold; +} + +.md-content ul { + margin-top: 0px; +} + +.md-content h3+p { + margin-block-start: 0px; + margin-top: 0px; +} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 74e7dd1ba..7d4e759a2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,33 +1,46 @@ site_name: ScoDoc theme: - name: mkdocs + # name: mkdocs + name: material navigation_depth: 3 + features: + - navigation.tabs + - toc.follow + - navigation.top + palette: + primary: light blue + language: fr + logo: assets/images/android-chrome-192x192.png + +extra_css: + - stylesheets/extra.css nav: - - Documentation: - - 'Guide utilisateur': GuideUtilisateur.md - - 'Tutos vidéos': https://www.youtube.com/playlist?list=PLw49h6RbvswhasBk9bXj7PzOD8GDW3kG1 - - 'Responsables de formations': GuideAdminFormation.md - - 'FAQ': FAQ.md - - - Installation: - - 'Guide administration': GuideAdminSys.md - - 'Installation': GuideInstallDebian11.md - - 'Mises à jour': MisesAJour.md - - 'Interfaces SI': InterrogationPortail.md - - 'Publication des notes': PublicationEtudiants.md - - 'Export Apogée': ScoDocApogee.md + - Accueil: index.md + - Documentation: + - "Guide utilisateur": GuideUtilisateur.md + - "Tutos vidéos": https://www.youtube.com/playlist?list=PLw49h6RbvswhasBk9bXj7PzOD8GDW3kG1 + - "Responsables de formations": GuideAdminFormation.md + - "Le BUT": BUT.md + - "FAQ": FAQ.md - - Association: - - 'Association 1901': AssociationScoDoc.md - - 'Utilisateurs': UtilisateursScoDoc.md + - Installation: + - "Guide administration": GuideAdminSys.md + - "Installation": GuideInstallDebian11.md + - "Mises à jour": MisesAJour.md + - "Interfaces SI": InterrogationPortail.md + - "Publication des notes": PublicationEtudiants.md + - "Export Apogée": ScoDocApogee.md + + - Association: + - "Association 1901": AssociationScoDoc.md + - "Utilisateurs": UtilisateursScoDoc.md - Développement: - - 'Git': https://scodoc.org/git - - 'Guide Développeurs': GuideDeveloppeurs.md - - 'API (interfaçages autres logiciels)': ScoDoc9API.md - + - "Git": https://scodoc.org/git + - "Guide Développeurs": GuideDeveloppeurs.md + - "API (interfaçages autres logiciels)": ScoDoc9API.md - FAQ: FAQ.md @@ -35,7 +48,7 @@ nav: # Pour LaTex, juste faire pip install python-markdown-math # dans l'environnement choisi (mkdocs) -#extra_javascript: +#extra_javascript: # - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML extra_javascript: @@ -45,4 +58,12 @@ extra_javascript: markdown_extensions: - pymdownx.arithmatex: - generic: true + generic: true + - footnotes + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format diff --git a/tools/publish b/tools/publish index 51b519b50..cfc909bb7 100755 --- a/tools/publish +++ b/tools/publish @@ -31,4 +31,4 @@ EOF (cd site && ln -s img/favicon.ico .) # --- Publish -rsync -vaze ssh site scodoc.org:/var/www/html +rsync -vaze ssh --delete site scodoc.org:/var/www/html