Instructions de compilaton

This document contains information on how to build the HTML, PDF, and EPUB versions of the frc-docs site. frc-docs uses Sphinx as the documentation generator. This document also assumes you have basic knowledge of Git and console commands.

Prérequis

Ensure that Git is installed and that the frc-docs repository is cloned by using git clone https://github.com/wpilibsuite/frc-docs.git.

Éditeurs de texte / IDE

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

Par défaut, l’extension reStructuredText active la vérification lint avec toutes les fonctionnalités doc8 activées. Comme frc-docs ne suit pas la vérification lint de longueur de ligne, ajoutez ce qui suit à votre code VS settings.json pour désactiver la vérification de la longueur de ligne.

"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

Installez les modules MikTex manquants en accédant au répertoire frc-docs, puis en exécutant la commande suivante dans 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

Lint Check will not check line endings on Windows due to a bug with line endings. See this issue for more 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 uses Poetry to manage its dependencies to make sure builds are reproducible.

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