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.
Éditeurs de texte / IDE
Pour le développement, nous recommandons l’utilisation de VS Code avec l’extension reStructuredText. Cela dit, n’importe quel éditeur de texte peut être utilisé.
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.
MiKTeX (Seulement requis pour les constructions PDF)
rsvg-convert (seulement requis pour la création de fichiers 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.
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
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 lien
Le vérificateur de lien s’assure que tous les liens dans la documentation sont correctement définis. Sinon, la compilation automatique échouera. Pour vérifier, exécutez .\make linkcheck
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