doc: documentation des commandes administratives

8 files changed, 109 insertions, 34 deletions

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 92ad7b7..c9e0b2a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -59,7 +59,10 @@ Utilisation de celcatsanitizer
    :maxdepth: 2
 
    usage/installation
-   usage/commands
+   usage/commands/cleancourses
+   usage/commands/listtimetables
+   usage/commands/reparse
+   usage/commands/timetables
    usage/versions
 
 Développement
diff --git a/Documentation/usage/commands.rst b/Documentation/usage/commands.rst
deleted file mode 100644
index 5dede31..0000000
--- a/Documentation/usage/commands.rst
+++ /dev/null
@@ -1,30 +0,0 @@
-================================================
-Manuel des commandes intégrées à celcatsanitizer
-================================================
-
-``cleancourses``
-================
-**ATTENTION : cette commande est irréversible.**
-
-Cette commande permet d’effacr tous les cours présents dans la base.
-
-``listtimetables``
-==================
-Affiche tous les emplois du temps présents dans la base de données,
-avec leur nom, leur source et leur identifiant interne dans la base de
-données.
-
-.. _ref-reparse:
-
-``reparse``
-===========
-Reparse les groupes dans la base de données.
-
-.. _ref-timetables:
-
-``timetables``
-==============
-Met à jour les emplois du temps présents dans la base de données.
-
-Il est fortement recommandé d’exécuter régulièrement cette commande
-:ref:`à l’aide d’une tâche cron <ref-cron>`.     
diff --git a/Documentation/usage/commands/cleancourses.rst b/Documentation/usage/commands/cleancourses.rst
new file mode 100644
index 0000000..4ca60b0
--- /dev/null
+++ b/Documentation/usage/commands/cleancourses.rst
@@ -0,0 +1,21 @@
+================
+``cleancourses``
+================
+
+``cleancourses`` permet d’effacer des cours présents dans la base de
+données. Il peut soit s’agir de tous les cours ou des cours d’une
+seule source.
+
+**ATTENTION : cette commande est irréversible.**
+
+
+Utilisation
+===========
+
+.. code:: shell
+
+   $ ./manage.py cleancourses [--source id]
+
+``--source`` permet de spécifier la suppression des cours provenant
+d’une seule source. ``id`` correspond à l’ID de la source, trouvable
+à l’aide de la commande :doc:`listtimetables`.
diff --git a/Documentation/usage/commands/listtimetables.rst b/Documentation/usage/commands/listtimetables.rst
new file mode 100644
index 0000000..94485b6
--- /dev/null
+++ b/Documentation/usage/commands/listtimetables.rst
@@ -0,0 +1,26 @@
+==================
+``listtimetables``
+==================
+
+``listtimetables`` affiche tous les emplois du temps présents dans la
+base de données, avec leur nom, leur source et leur identifiant
+interne dans la base de données.
+
+Utilisation
+===========
+.. code:: shell
+
+    $ ./manage.py listtimetables
+
+Format de sortie
+================
+Cette commande affiche les sources avec leur URL et leur ID interne
+(utilisable avec la commande :doc:`cleancourses`), ainsi que la liste
+des emplois du temps associés à cette source.
+
+Exemple de sortie
+-----------------
+::
+
+    L1 Info, L1 Miashs      : https://edt.univ-tlse3.fr/FSI/2017_2018/L1/L1_SN/g222621.xml (id: 3)
+    L2 Info : https://edt.univ-tlse3.fr/FSI/2017_2018/L2/L2_Info/g224636.xml (id: 13)
diff --git a/Documentation/usage/commands/reparse.rst b/Documentation/usage/commands/reparse.rst
new file mode 100644
index 0000000..78a54b7
--- /dev/null
+++ b/Documentation/usage/commands/reparse.rst
@@ -0,0 +1,11 @@
+===========
+``reparse``
+===========
+
+``reparse`` reparse tous les groupes dans la base de données.
+
+Utilisation
+===========
+.. code:: shell
+
+    $ ./manage.py reparse
diff --git a/Documentation/usage/commands/timetables.rst b/Documentation/usage/commands/timetables.rst
new file mode 100644
index 0000000..723b5aa
--- /dev/null
+++ b/Documentation/usage/commands/timetables.rst
@@ -0,0 +1,44 @@
+==============
+``timetables``
+==============
+
+``timetables`` met à jour les emplois du temps présents dans la base
+de données.
+
+Il est fortement recommandé d’exécuter régulièrement cette commande
+:ref:`à l’aide d’une tâche cron <ref-cron>`.
+
+Utilisation
+===========
+.. code:: shell
+
+    $ ./manage.py timetables [--all] [--force] [--week week] [--year year]
+
+Par défaut, ``timetables`` met à jour seulement la semaine courante ou
+à venir le week-end, et ne met pas à jour si la dernière mise à jour
+présente dans la base de données est plus récente que celle présente
+dans la source. Les différents paramètres permettent de contrôler ce
+comportement :
+
+``--all`` permet de mettre à jour toutes les semaines présentes dans
+la source.
+
+``--force`` force la mise à jour, même si la dernière mise à jour des
+emplois du temps présente dans la base de données est plus récente que
+celle présente dans la source.
+
+``--week`` permet de spécifier la semaine à mettre à jour.
+
+``--year`` permet de spécifier l’année à mettre à jour.
+
+Comportement
+============
+Pour chaque emploi du temps, ``timetables`` récupère la source,
+supprime les cours sur la période couverte par cette mise à jour,
+parse la source et insère les cours dans la base de données.
+
+Cette mise à jour est effectuée de manière transactionnelle : si la
+mise à jour d’une source échoue au milieu du processus, les données
+supprimées au début seront entièrement restaurées, les données
+rajoutées seront supprimées, et une erreur sera affichée. Cela
+n’affecte pas la mise à jour des autres emplois du temps.
diff --git a/Documentation/usage/installation.rst b/Documentation/usage/installation.rst
index 7290df1..e3ae9e9 100644
--- a/Documentation/usage/installation.rst
+++ b/Documentation/usage/installation.rst
@@ -231,8 +231,8 @@ Cette étape est **fortement recommandée**.
 Cron
 ----
 Pour mettre à jour les emplois du temps de manière régulière, il faut
-rajouter :ref:`la commande de mise à jour <ref-timetables>` dans une
-tâche cron.
+rajouter :doc:`la commande de mise à jour <commands/timetables>` dans
+une tâche cron.
 
 Lancement
 =========
diff --git a/Documentation/usage/versions.rst b/Documentation/usage/versions.rst
index 0f354bc..d6b8f00 100644
--- a/Documentation/usage/versions.rst
+++ b/Documentation/usage/versions.rst
@@ -31,5 +31,5 @@ Changements internes
    du temps. Cela permet d’éviter de récupérer plusieurs fois le même
    fichier et d’éviter les doublons sur les emplois du temps des
    salles.
- - Ajout de la commande :ref:`reparse <ref-reparse>`
+ - Ajout de la commande :doc:`reparse <commands/reparse>`
  - Meilleure abstraction des templates, notamment de ``index.html``