doc: initial readme

README.md

+# lflex-celcat-survival
+Set of tools to stay sane while using a CELCAT calendar at UT3.
+
+### Rationale
+As I write these lines, [the CELCAT calendar available at UT3](https://edt.univ-tlse3.fr/) cannot be used directly for teachers to know their courses. This is mainly because course time slots are not attached to teachers in the database, and many different teachers may participate in the same course. The result is that, when you want to know what courses you give next week, you end up with hundreds of time slots instead of just the deired ones.
+
+This project tries to make CELCAT usable by:
+- Fetching event data from the internal CELCAT REST API
+- Filtering out all the events that do not correspond to the courses you give
+- Generating an ICS with all the remaining events
+- **TODO**: Providing a way to sync ics with a CalDAV server, to enable all calendar clients to synchronize from it
+
+### Usage
+`fetch-ics <COURSE-REQUESTS-FILE.csv> [-o <OUTPUT-FILE.ics>]`
+
+The course request input file defines which courses you are interested in.
+For example, if you give the following courses:
+
+- BAS (apogee code KINXIB11)
+  - 5 TD with group INXIB11A4 from 2022-09-05 to 2022-10-22
+  - 3 TP with group INXIB11A42 from 2022-09-05 to 2022-10-22
+- SR1 (apogee code KINXIB21)
+  - 5 TP with group INXIB21A42 from from 2022-09-05 to 2022-10-22
+
+an equivalent CSV file would be the following:
+
+```
+module_apogee,module_readable,begin_date,end_date,course_type,group,expected_nb_slots
+KINXIB11,BAS,2022-09-05 00:00:00,2022-10-21 23:59:00,TD,INXIB11A4,5
+KINXIB11,BAS,2022-09-05 00:00:00,2022-10-21 23:59:00,TP,INXIB11A42,3
+KINXIB21,SR1,2022-09-05 00:00:00,2022-10-21 23:59:00,TP,INXIB21A42,5
+```
+
+### Use this script with caution
+The only life jacket of this script is that it prints a warning if the number of fetched events is not the expected one for each course request.
+
+The script works for all the courses I give (BAS, SR1, SR2, Parallélisme) as I write these lines (2022-09-11).
+However, the approach is not robust so it may break when:
+- There is a CELCAT server update (REST API break)
+- There is a change on how CELCAT events are formatted in the UT3 database (description parsing is hardcoded and not robust)
+
+### Installation
+If you are using [Nix](https://nixos.org/) with [flakes enabled](https://nixos.wiki/wiki/Flakes#Enable_flakes), you can directly run the latest version of this code without any installation:
+```sh
+nix run git+https://gitlab.irit.fr/poquet/lflex-celcat-survival\?ref=main#fetch-ics -- request-file.csv -o out.ics
+```
+
+If you are using [Nix](https://nixos.org/), you can enter a shell where the program is available by typing this command:
+```sh
+nix-shell https://gitlab.irit.fr/poquet/lflex-celcat-survival/-/archive/main/lflex-celcat-survival-main.tar.gz -A user-shell
+# then, inside the temporary shell: fetch-ics request-file.csv -o out.ics
+```
+
+If you are using [Nix](https://nixos.org/) but want to install this software instead:
+```sh
+nix-env -f https://gitlab.irit.fr/poquet/lflex-celcat-survival/-/archive/main/lflex-celcat-survival-main.tar.gz -iA lflex_celcat_survival
+# then, whenever you want: fetch-ics request-file.csv -o out.ics
+```
+
+If you are not using [Nix](https://nixos.org/), you can do a local installation via [pip](https://pip.pypa.io/en/stable/):
+```sh
+pip install git+https://gitlab.irit.fr/poquet/lflex-celcat-survival
+# then, whenever you want: fetch-ics request-file.csv -o out.ics
+```