Instructions de compilaton

Ce document présente l’information nécessaire pour compiler les versions HTML, PDF, et EPUB du site frc-docs. Le projet frc-docs utilise Sphinx comme générateur de documentation. Ce document suppose également que vous avez une connaissance de base de Git et des commandes de la console.

Prérequis

Assurez-vous que Git est installé et que la bibliothèque frc-docs est dupliquée en utilisant git clone https://github.com/wpilibsuite/frc-docs.git.

Windows

Note

La plupart des modules MikTeX ne sont pas requis pour compiler du HTML, par contre des modules supplémentaires peuvent être nécessaires pour compiler en PDF ou EPUB.

Assurez-vous que Python fait partie de votre chaîne Path en sélectionnant l’option Add Python to PATH lors de l’installation de Python.

Showing where to click the box to add Python to PATH.

Une fois Python installée, ouvrez Powershell, puis localisez le répertoire frc-docs. Exécutez la commande suivante: pip install -r source/requirements.txt

Installez les modules MikTex manquants en localisant le répertoire frc-docs, puis en exécutant la commande suivante dans Powershell: mpm --verbose --require=@miktex-packages.txt

Finalement, vous devez installer rsvg-convert en exécutant le script scripts/install-rsvg-convert.ps1 dans powershell. Cette opération nécessite un accès en tant qu’administrateur.

Linux (Ubuntu)

$ sudo apt update
$ sudo apt install python3 python3-pip
$ python3 -m pip install -U pip setuptools wheel
$ python3 -m pip install -r source/requirements.txt
$ sudo apt install -y texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra latexmk texlive-lang-greek texlive-luatex texlive-xetex texlive-fonts-extra dvipng librsvg2-bin

Compilation

Ouvrez une console ou une fenêtre Powershell Window et localisez le répertoire frc-docs qui a été dupliqué.

PS > cd "%USERPROFILE%\Documents"
PS C:\Users\Example\Documents> git clone https://github.com/wpilibsuite/frc-docs.git
Cloning into 'frc-docs'...
remote: Enumerating objects: 217, done.
remote: Counting objects: 100% (217/217), done.
remote: Compressing objects: 100% (196/196), done.
remote: Total 2587 (delta 50), reused 68 (delta 21), pack-reused 2370
Receiving objects: 100% (2587/2587), 42.68MiB | 20.32 MiB/s, done.
Receiving deltas: 100% (1138/1138), done/
PS C:\Users\Example\Documents> cd frc-docs
PS C:\Users\Example\Documents\frc-docs>

Vérificateur syntaxique

Note

Le vérificateur syntaxique ne vérifiera pas les fins de phrases sur Windows à cause d’un bug lié aux fins de phrases. Consultez ce problème pour plus d’information.

Il est suggéré de vérifier les changements apportés avec le vérificateur syntaxique. Sinon, la compilation automatique échouera. Pour vérifier, exécutez .\make lint

Vérificateur de taille des images

Exécutez .\make sizecheck pour vérifier que toutes les images font moins de 500ko. Les excès feront échouer l’intégration continue. Des exceptions seront permises au cas par cas et elles seront ajoutées à la liste IMAGE_SIZE_EXCLUSIONS du fichier de configuration.

Rediriger la vérification

Les fichiers qui ont été déplacés ou renommés doivent avoir leur nouvel emplacement (ou remplacé par 404) dans le fichier redirects.txt dans la source.

Le rédacteur de redirection ajoutera automatiquement les fichiers renommés ou déplacés au fichier de redirection. Run .\make rediraffewritediff.

Note

si un fichier est à la fois déplacé et substantiellement modifié, le rédacteur de la redirection ne l’ajoutera pas au fichier redirects.txt, et redirects.txt aura besoin d’être mis à jour manuellement.

Le vérificateur de redirection s’assure qu’il existe des redirections valides pour tous les fichiers. Cela ** fera ** échouer le buildbot s’il ne réussit pas. Pour vérifier, exécutez .\make rediraffecheckdiff pour vérifier que tous les fichiers sont redirigés. De plus, une version HTML peut devoir être exécutée pour garantir que tous les fichiers sont correctement redirigés.

Compilation en HTML

Exécutez .\make html pour générer le contenu en HTML. Le contenu HTML est situé dans le répertoire build/html à la racine de la bibliothèque.

Compilation en PDF

Avertissement

Notez que la compilation PDF sous Windows peut causer la distorsion d’image au format SVG. Ceci est dû au manque de ressources librsvg2-bin sur Windows.

Exécutez .\make latexpdf pour générer le contenu en PDF. Le contenu PDF est situé dans le répertoire build/latex à la racine de la bibliothèque.

Compilation en EPUB

Exécutez .\make epub pour générer le contenu en EPUB. Le contenu EPUB est situé dans le répertoire build/epub à la racine de la bibliothèque.

Ajout de librairies tierces Python

Important

Après avoir modifié les dépendances frc-docs de quelque manière que ce soit, requirements.txt doit être régénéré en exécutant poetry export -f requirements.txt --output source/requirements.txt --without-hashes à partir de la racine du repo.

frc-docs utilise Poetry pour gérer ses dépendances afin de s’assurer que les versions sont reproductibles.

Note

Poetry n’est ** pas ** nécessaire pour créer et contribuer au contenu frc-docs. Il est * uniquement * utilisé pour la gestion des dépendances.

Installation de Poetry

Assurez-vous que Poetry est installé. Exécutez la commande suivante: `` pip install poetry “”

Ajouter une dépendance

Ajoutez la dépendance à la section [tool.poetry.dependencies] de pyproject.toml. Assurez-vous de spécifier une version exacte. Ensuite, exécutez la commande suivante: poetry lock --no-update

Mise à jour d’une dépendance de niveau supérieur

Mettez à jour la version de la dépendance dans la section [tool.poetry.dependencies] de pyproject.toml. Ensuite, exécutez la commande suivante: poetry lock --no-update

Mise à jour des dépendances masquées

Exécutez la commande suivante: poetry lock