Instrucciones de Construcción

Este documento contiene información sobre cómo construir las versiones de HTML, PDF, y EPUB del sitio frc-docs. frc-docs usa Sphinx como generador de documentación. Éste documento también asume que usted tiene los conocimientos básicos de Git y los comandos de consola.

Prerrequisitos

Asegúrese de que Git esté instalado y que el repositorio de frc-docs se clone utilizando git clone https://github.com/wpilibsuite/frc-docs.git.

Editores de texto / IDE

Para desarrollo, recomendamos que uses VS Code junto con la extensión reStructuredText. Sin embargo, cualquier editor de texto funcionará.

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.

  • Python 3.9

  • Perl

  • MiKTeX <https://miktex.org/download> __ (Solo necesario para compilaciones PDF)

  • rsvg-convert (Solo necesario para generar PDF)

Asegúrese de que Python esté en su PATH, marcando la casilla Agregar Python a PATH al instalar Python.

Mostrando dónde hacer clic en la casilla para añadir Python al PATH.

Una vez que Python esté instalado, abra Powershell. Luego navegue al directorio frc-docs. Ejecute el siguiente comando: pip install -r source/requirements.txt

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

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 no marcará los bordes en Windows debido al error de los bordes. Vea este problema para más información.

Se recomienda verificar cualquier cambio que realice con el linter. Esto podría fallar el buildbot si no pasa. Para verificar, ejecute .\make lint

Verificar el tamaño de imagen

Ejecute .\make sizecheck para verificar que todas las imágenes tengan menos de 500 KB. Esta verificación fallará CI si falla. Las exclusiones se permiten caso por caso y se agregan a la lista IMAGE_SIZE_EXCLUSIONS en el archivo de configuración.

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.

El escritor de redireccionamiento agregará automáticamente archivos renombrados / movidos al archivo de redireccionamientos. Ejecute .\make 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.

El comprobador de redireccionamiento se asegura de que haya redireccionamientos válidos para todos los archivos. Esto fallará al buildbot si no pasa. Para comprobarlo, ejecute .\make rediraffecheckdiff para verificar que todos los archivos estén redirigidos. Además, es posible que sea necesario ejecutar una compilación HTML para garantizar que todos los archivos se redireccionen correctamente.

Construyendo HTML

Escriba el comando .\make html para generar un contenido HTML. Éste contenido esta ubicado en el directorio build/html en la raíz del repositorio.

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.

Escriba el comando .\make latexpdf para generar el contenido PDF. El PDF está localizado en el directorio build/latex en la raíz del repositorio.

Construyendo EPUB

Escriba el comando .\make epub para generar un contenido EPUB. El EPUB está ubicado en el directorio build/epub en la raíz del repositorio.

Agregar bibliotecas de terceros de Python

Importante

Después de modificar las dependencias de frc-docs de cualquier manera, requirements.txt debe regenerarse ejecutando poetry export -f requirements.txt --output source/requirements.txt --without-hashes desde la raíz de el repositorio.

frc-docs usa Poetry para administrar sus dependencias para asegurarse que contrucciones sean reproducibles.

Nota

Poetry no es necesaria para crear y contribuir al contenido de frc-docs. Solo se utiliza para la gestión de dependencias.

Instalar Poetry

Asegúrese de que Poetry esté instalado. Ejecute el siguiente comando: pip install poet.

Agregar una dependencia

Agregue la dependencia a la sección [tool.poetry.dependencies] de pyproject.toml. Asegúrese de especificar una versión exacta. Luego, ejecute el siguiente comando: poetry lock --no-update.

Actualizar una dependencia de nivel superior

Actualice la versión de la dependencia en la sección [tool.poetry.dependencies] de pyproject.toml. Luego, ejecute el siguiente comando: poetry lock --no-update.

Actualizar dependencias ocultas

Ejecute el siguiente comando: poetry lock.