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.
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.
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 will not check line endings on Windows due to a bug with line endings. See this issue for more information.
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 enlace
El verificador de enlace asegura que todos los enlaces/links en la documentación estén resueltos. Esto podría fallar el buildbot si no pasa. Para verificar, ejecute .\make linkcheck
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 uses Poetry to manage its dependencies to make sure builds are reproducible.
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.