Modulo est basé sur le générateur de documentation Sphinx et utilise le template Furo. Les ressources sont rédigées au format Markdown et sont générées par Sphinx sous la forme d'un site web statique (HTML/CSS/JS).
- Python 3.x et pip (Installation MacOSX) (Installation Windows) (Installation rapide)
- virtualenv (
$ pip install virtualenv) - Git
Pour vérifier la bonne installation de l'environnement de base :
$ python --version$ virtualenv --version$ git --version
Pour simplifier les actions fréquentes (build, clean), le projet contient un Workspace pour Visual Studio Code. Lors de l'ouverture du Workspace (à la racine du projet), il vous sera proposé d'installer les plugins suggérés. L'utilisation de VSCode est optionnelle, mais le Workspace propose des boutons qui vous éviteront de saisir certaines commandes à la main dans le Terminal.
- Récupération du projet :
git clone git@github.com:edunumsec2/book.git(ou alors plus simplement avec GitHub Desktop) - Déplacement vers la racine du projet :
cd book - Création d'un environnement virtuel :
virtualenv .env - Activation de l'environnement virtuel
MacOS :source .env/bin/activate
Windows :.env\Scripts\activate - Installation des librairies dans l'environnement virtuel :
pip install -r requirements.txt -U, puisplaywright install chromium(nécessaire seulement pour la génération de la version imprimable)
Remarque : à chaque fois que vous travaillez sur le projet, l'environnement virtuel doit être activé (point 4). Si vous utilisez VSCode et le Workspace, les boutons de build/auto-build l'activent automatiquement.
Le projet utilise sphinx-autobuild qui démarre un serveur sur http://localhost:8000 (ou http://127.0.0.1:8000) et rebuild la documentation automatiquement lorsqu'un changement est détecté.
- Activation de l'environnement virtuel (si pas déjà fait)
- Activation du serveur local :
- Documentation 'Apprendre' :
sphinx-autobuild src/appr build --watch src --open-browser -a --delay 1 - Documentation 'Enseigner' :
sphinx-autobuild src/ens build --watch src --open-browser -a --delay 1
Pour arrêter le serveur : Ctrl+c ou ⌘+c
Remarque: si vous utilisez le workspace VSCode, vous pouvez utiliser les boutons proposés en bas de l'interface.
- Génération du build 'Apprendre' :
sphinx-build -b html src/appr build - Génération du build 'Enseigner' :
sphinx-build -b html src/ens build
Remarque: si vous utilisez le workspace VSCode, vous pouvez utiliser les boutons proposés en bas de l'interface.
La génération automatique d'un polycopié est actuellement en développement et n'est pas encore stabilisée. De plus elle n'est testée pour l'instant que sur Mac OS.
Sphinx permet de générer un build LaTeX des sources qui peut ensuite être utilisé pour générer une polycopié au format pdf.
- Génération du fichier latex:
sphinx-build -b latex -t latex_mode src/appr build/latex/appr - Compilation du fichier latex:
cd build/latex/appr && make
Les options de build, notamment les chapitres à générer, le titre, le noms des auteurs, les couleurs etc., peuvent être modifées dans le fichier src/appr/conf.py et src/ens/conf.py