Instrucciones de Construcción
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.
Prerrequisitos
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.
Editores de texto / IDE
For development, we recommend that you use VS Code along with the reStructuredText extension. However, any text editor will work.
Por defecto, la extensión reStructuredText habilita el linting con todas las características de doc8 habilitadas. Como frc-docs no sigue el lint de longitud de línea, agrega lo siguiente a tu archivo settings.json de VS Code para deshabilitar el linting de longitud de línea.
"restructuredtext.linter.doc8.extraArgs": [
"--ignore D001"
]
Windows
Nota
MikTeX y rsvg-convert no son necesarios para compilaciones de HTML, sólo son necesarios para PDF en Windows.
MiKTeX (Only needed for PDF builds)
rsvg-convert (Only needed for PDF builds)
Asegúrese de que Python esté en su PATH, marcando la casilla Agregar Python a PATH al instalar Python.
Instala los paquetes faltantes de MikTex navegando al directorio frc-docs, luego ejecuta el siguiente comando desde 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
Compilando
Abra una ventana o terminal de Powershell y navegue hasta el directorio frc-docs que fue clonado.
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>
Lint Check
Nota
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
Verificar el enlace
The link checker makes sure that all links in the documentation resolve. This will fail CI if it does not pass. To check, run uv run .\make.bat linkcheck
Verificar el tamaño de imagen
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.
Verificar redirección
Los archivos que se han movido o cambiado de nombre deben tener su nueva ubicación (o reemplazarse con 404) en el archivo redirects.txt en source.
The redirect writer will automatically add renamed/moved files to the redirects file. Run uv run .\make.bat rediraffewritediff.
Nota
Si un archivo se mueve y se modifica sustancialmente, el escritor de redirecciones no lo agregará al archivo redirects.txt y el archivo redirects.txt deberá actualizarse manualmente.
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.
Construyendo 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.
Construyendo un PDF
Advertencia
Por favor note que un PDF hecho en Windows puede resultar en imágenes distorsionadas por el contenido SVG. Esto se debe a la falta de soporte de librsvg2-bin en 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.
Construyendo 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.
Agregar bibliotecas de terceros de Python
Importante
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.
Agregar una dependencia
Add the dependency to the dependencies array in pyproject.toml. Make sure to specify an exact version. Then, run the following command: uv lock.
Actualizar una dependencia de nivel superior
Update the dependency’s version in the dependencies array in pyproject.toml. Then, run the following command: uv lock.