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.

You will need to install uv, a Python package and project manager. Follow the installation instructions for your operating system.

É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.

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
$ 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.

It’s encouraged to check any changes you make with the linter. This will fail CI if it does not pass. To check, run uv run .\make.bat lint

Vérificateur de taille des images

Please run uv run .\make.bat 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.

The redirect writer will automatically add renamed/moved files to the redirects file. Run uv run .\make.bat 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.

The redirect checker makes sure that there are valid redirects for all files. This will fail CI if it does not pass. To check, run uv run .\make.bat rediraffecheckdiff to verify all files are redirected. Additionally, an HTML build may need to be ran to ensure that all files redirect properly.

Compilation en HTML

Type the command uv run .\make.bat html to generate HTML content. The content is located in the build/html directory at the root of the repository.

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.

Type the command uv run .\make.bat latexpdf to generate PDF content. The PDF is located in the build/latex directory at the root of the repository.

Compilation en EPUB

Type the command uv run .\make.bat epub to generate EPUB content. The EPUB is located in the build/epub directory at the root of the repository.

Ajout de librairies tierces Python

Important

After modifying frc-docs dependencies in any way, requirements.txt must be regenerated by running uv export --frozen --no-dev --no-editable -o source/requirements.txt from the root of the repo.

Ajouter une dépendance

Add the dependency to the dependencies array in pyproject.toml. Make sure to specify an exact version. Then, run the following command: uv lock.

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

Update the dependency’s version in the dependencies array in pyproject.toml. Then, run the following command: uv lock.

Updating All Hidden Dependencies

Run the following command: uv lock --upgrade.

Updating a Specific Hidden Dependency

Run the following command: uv lock --upgrade-package <package>.