Documentation (#12)

* Add documentation base files

* update README

.github/workflows/manual.yaml

@@ -0,0 +1,44 @@
+on:
+ # Creating a release requires a tag
+ push:
+ tags:
+ "*"
+ paths:
+ - 'docs/manuel/**'
+ - '.github/workflows/manual.yaml'
+
+jobs:
+ build-manual:
+ runs-on: ubuntu-22.04
+ container:
+ image: rust:latest
+ options: --user 1001 # So we avoid ownership issues
+ env:
+ book-dir: ./docs/manuel
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Declare some variables
+ shell: bash
+ run: |
+ echo "sha_short=$(git rev-parse --short "$GITHUB_SHA")" >> "$GITHUB_ENV"
+ echo "branch=$(echo $GITHUB_REF | sed 's/refs\/\(tags\|heads\)\///;s/\//_/g')" >> "$GITHUB_ENV"
+
+ # Install mdbook
+ - name: Install `mdbook`
+ run: cargo install mdbook
+
+ # Build the book
+ - name: Build the book
+ run: |
+ mdbook build
+ mv book manuel-langate-${{ env.sha_short }}
+ tar zcvf manuel.tar.gz manuel-langate-${{ env.sha_short }}
+ working-directory: ${{ env.book-dir }}
+
+ # Create a release
+ - name: Create a release
+ uses: softprops/action-gh-release@v1
+ with:
+ files: ${{ env.book-dir }}/manuel.tar.gz
+

README.md

@@ -3,9 +3,13 @@
 This repository is here to hold the langate infrastructure. It is composed of
 the frontend, the backend, and the nginx server.
 
+## Documentation
+
+Technical documentation is available [here](docs/manuel/src/SUMMARY.md) (in french).
+
 ## Contributing
 
-Please read carefully[the CONTRIBUTING.md file](CONTRIBUTING.md) before any
+Please read carefully [the CONTRIBUTING.md file](CONTRIBUTING.md) before any
 contribution.
 
 ## Netcontrol
@@ -65,4 +69,4 @@ Docker can take a lot of disk space with all the images.
 You have a few options to clean it up:
 
 - `make clean-all` will remove all the containers and images
-- `make clean-custom` will remove all the custom images (the ones we build and not the ones we pull from docker hub)
+- `make clean-custom` will remove all the custom images (the ones we build and not the ones we pull from docker hub)

docs/manuel/.gitignore

@@ -0,0 +1 @@
+book

docs/manuel/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Hector \"pixup1\" Vernet"]
+language = "fr"
+multilingual = false
+src = "src"
+title = "Manuel de la Langate3000"

docs/manuel/src/00-backend/README.md

@@ -0,0 +1,3 @@
+# Backend
+
+Le backend de la langate est écrit en Python et utilise [DRF](django-rest-framework.org).

docs/manuel/src/00-backend/modeles.md

@@ -0,0 +1 @@
+# Modèles

docs/manuel/src/00-backend/netcontrol.md

@@ -0,0 +1,7 @@
+# Netcontrol
+
+Netcontrol est le composant de la langate qui interface le backend avec la tête de réseau.
+
+Il permet à la langate de pouvoir effectuer des opérations de plus bas niveau grace à un niveau de privilège plus élevé sur la tête.
+
+Il communique via sockets UNIX. Les informations sont précédées d'une annonce de leur taille, sous la forme d'un int de 4 octets. Les informations en elles-mêmes sont toujours des dictionnaires Python encodés en [pickle](https://docs.python.org/3/library/pickle.html).

docs/manuel/src/00-backend/urls.md

@@ -0,0 +1 @@
+# URLs

docs/manuel/src/00-backend/vues.md

@@ -0,0 +1 @@
+# Vues

docs/manuel/src/01-frontend/README.md

@@ -0,0 +1,3 @@
+# Frontend
+
+Le frontend est écrit en [Vue](https://fr.vuejs.org).

docs/manuel/src/01-frontend/gestion.md

@@ -0,0 +1,9 @@
+# Page de gestion
+
+C'est cette page qui permet aux administrateurs de gérer les joueurs et les appareils connectés au réseau. Elle permet de :
+
+- Ajouter / supprimer des utilisateurs
+- Whitelist des appareils
+- Kick / Ban des joueurs ou des appareils
+
+Django dispose d'une page de management native assez capable, mais nous avons choisi d'en faire une custom.

docs/manuel/src/01-frontend/style.md

@@ -0,0 +1,3 @@
+# Style
+
+Le thème de la langate est réalisé en Tailwind.

docs/manuel/src/01-frontend/vues.md

@@ -0,0 +1,11 @@
+# Vues
+
+Le front est composé des vues suivantes :
+
+- Page de connexion
+- Page d'accueil
+- Page d'erreur
+- Page de la FAQ
+- [Page de gestion](gestion.md)
+- Page de création de ticket
+- Page de gestion des tickets

docs/manuel/src/README.md

@@ -0,0 +1,49 @@
+# Introduction
+
+Ce manuel a pour but de documenter le fonctionnement de la [langate 3000](https://github.com/InsaLan/langate3000) (réécrite en 2024). La langate étant bâtie sur beaucoup des mêmes technologies que le site web, une documentation plus extensive sur ces technologies est disponible dans le [manuel de prise en main du backend](https://docs.insalan.fr/backend/).
+
+Le manuel de la langate est présenté, comme celui du site, sous une license [Creative Commons BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).
+
+## Langate ?
+
+La langate est le portail captif de l'InsaLan, utilisé en Mini et à la LAN. Elle fournit les fonctionnalités suivantes :
+- Gestion d'utilisateurs (statut de paiement, gestion des privilèges)
+- Synchronisation des comptes utilisateurs avec le site web
+- Gestion d'appareils (whitelist)
+- Panneau de gestion custom
+- Tickets
+- Annonces
+
+## Historique
+
+Au commencement, il n'y avait rien. Puis il y eut l'InsaLan. La première date d'utilisation d'un portail captif n'est pas connue, peut-être que les archives sont incomplètes, cependant on en trouve plusieurs mentions sur l'ancien wiki.
+
+La [langate 2000](https://github.com/InsaLan/langate2000) fut mise en service en 2019 pour l'InsaLan XIV. Elle était codée avec des technologies similaires à la langate actuelle (surtout le back, qui était déjà en Django), mais sans documentation.
+
+Il a donc été décidé de créer cette version de la langate. Elle nous permettra d'avoir une documentation et une compréhension complète de son fonctionnement, et elle sera ainsi plus facile à maintenir et améliorer.
+
+## Technologies
+
+Cette langate, comme le site web, utilise [Nginx](nginx.com) et [DRF](django-rest-framework.org) (outil permettant de développer des API web en **Python**) pour le back et [Vue](https://fr.vuejs.org) pour le front.
+
+On la déploie avec [Docker](docker.com).
+
+## L'équipe
+
+La langate 3000 est le fruit d'une coopération historique entre les équipes SysRez-Dev et SysRez-Infra, et plus spécifiquement :
+
+- Gabriel "**KwikKill**" Blaisot [il], responsable SysRez-Dev de l'InsaLan XIX
+- Paul "**TheBloodMan**" Gasnier [il], responsable SysRez-Infra de l'InsaLan XVIII
+- Amance "**Ecnama**" Graindorge [il], responsable SysRez-Infra de l'InsaLan XIX
+- Hector "**pixup1**" Vernet [il], responsable SysRez-Infra de l'InsaLan XIX
+
+Elle repose bien évidemment sur le travail des légendes à l'origine de la langate 2000 :
+
+- **Mahal** / ShiroUsagi-san
+- **Red** / red4game
+- **Flo** / darkgallium
+- **Lin HD** / cloudyhug
+- **Kuro** / antonincms
+- **Trinity** / trinity-1686a
+- **Lux** / Lymkwi
+- **ElPainAuChocolat** / NathanPERIER

docs/manuel/src/SUMMARY.md

@@ -0,0 +1,14 @@
+# Sommaire
+
+[Introduction](README.md)
+
+- [Backend](00-backend/README.md)
+ - [URLs](00-backend/urls.md)
+ - [Modèles](00-backend/modeles.md)
+ - [Vues](00-backend/vues.md)
+ - [Netcontrol](00-backend/netcontrol.md)
+
+- [Frontend](01-frontend/README.md)
+ - [Vues](01-frontend/vues.md)
+ - [Page de gestion](01-frontend/gestion.md)
+ - [Style](01-frontend/style.md)