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.

Text Editors / IDE

For development, we recommend that you use VS Code along with the reStructuredText extension. However, any text editor will work.

By default, the reStructuredText extension enables linting with all doc8 features enabled. As frc-docs does not follow the line length lint, add the following to your VS Code settings.json to disable line length linting.

"restructuredtext.linter.doc8.extraArgs": [
   "--ignore D001"
]

Windows

Note

MikTeX et rsvg-convert ne sont pas requis pour la construction HTML, ils ne sont requis que pour les constructions Windows PDF.

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.

Montrant où cliquer sur la zone pour ajouter Python à 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

Install the missing MikTex packages by navigating to the frc-docs directory, then running the following command from Powershell: miktex --verbose packages require --package-id-file miktex-packages.txt

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

Please run .\make sizecheck to verify that all images are below 500KB. This check will fail CI if it fails. Exclusions are allowed on a case by case basis and are added to the IMAGE_SIZE_EXCLUSIONS list in the configuration file.

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

Ensure that Poetry is installed. Run the following command: pip install poetry.

Ajouter une dépendance

Add the dependency to the [tool.poetry.dependencies] section of pyproject.toml. Make sure to specify an exact version. Then, run the following command: poetry lock --no-update.

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

Update the dependency’s version in the [tool.poetry.dependencies] section of pyproject.toml. Then, run the following command: poetry lock --no-update.

Mise à jour des dépendances masquées

Run the following command: poetry lock.