🔧 Outils avancés

MkDocs — Créer un site de documentation

MkDocs est l'outil utilisé pour créer ce site ! Il génère des sites web à partir de fichiers Markdown.

Installation

pip install mkdocs mkdocs-material

Démarrage rapide

mkdocs new monsite   # Crée un nouveau projet
cd monsite
mkdocs serve         # Lance un serveur local de prévisualisation
mkdocs build         # Génère le site statique dans le dossier /site

Personnaliser les couleurs (extra.css)

Créez docs/stylesheets/extra.css et ajoutez-le dans mkdocs.yml :

extra_css:
  - stylesheets/extra.css

MkDocs en français

pip install mkdocs[i18n]

Dans mkdocs.yml :

theme:
  name: material
  language: fr

theme:
  features:
    - navigation.footer

MdBook — Créer un livre interactif

MdBook est un outil en Rust pour créer des livres/documentations en ligne.

Installer Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Répondre : 1 (Entrée)

Ajouter Rust au PATH dans ~/.bashrc :

export PATH=$PATH:~/.cargo/bin
source ~/.bashrc

Installer MdBook

cargo install mdbook
mdbook --version     # Vérifier l'installation

Créer un projet

mdbook init monlivre

Structure générée :

monlivre/
├── book.toml
└── src/
    ├── SUMMARY.md
    └── chapter_1.md

Ajoutez vos chapitres dans SUMMARY.md, puis construisez le livre :

mdbook build
mdbook serve    # Prévisualisation locale

Python — Environnements virtuels

Pour éviter les conflits entre projets Python, utilisez les environnements virtuels :

sudo apt install python3-full python3-venv python3-pip

cd mon_projet
python3 -m venv venv         # Crée l'environnement virtuel
source venv/bin/activate     # Active l'environnement
# (venv) apparaît dans le prompt

pip install nompaquet        # Installe des paquets dans l'environnement isolé

deactivate                   # Désactive l'environnement
rm -rf venv                  # Supprime l'environnement si besoin

Cette méthode évite l'erreur externally-managed-environment sur les systèmes récents.

Pages GitHub

Pour héberger gratuitement votre site MkDocs sur GitHub Pages :

mkdocs gh-deploy

Documentation officielle : docs.github.com/fr/pages

Problème d'arrêt sur certains PC Acer

Si votre PC Acer ne s'éteint pas correctement :

sudo nano /etc/default/grub
# Modifier la ligne :
GRUB_CMDLINE_LINUX_DEFAULT="pci=nocrs"

sudo update-grub

Refus de francisation sous LightDM

Si la langue clavier ne persiste pas au redémarrage :

sudo systemctl stop lightdm
sudo dpkg-reconfigure keyboard-configuration
sudo systemctl start lightdm

Ou vider le fichier de configuration LightDM :

sudo nano /etc/lightdm/lightdm.conf
# Supprimer tout le contenu, Ctrl+O pour sauvegarder, redémarrer