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.
Text Editors / IDE
For development, we recommend that you use VS Code along with the reStructuredText extension. However, any text editor will work.
Windows
Nota
MikTeX y rsvg-convert no son necesarios para compilaciones de HTML, sólo son necesarios para PDF en Windows.
MiKTeX <https://miktex.org/download> __ (Solo necesario para compilaciones PDF)
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
Instale los paquetes faltantes de MikTex navegando al directorio frc-docs, y ejecutando el siguiente comando en Powershell: mpm --verbose --require=@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 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
Please run .\make 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.
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
Ensure that Poetry is installed. Run the following command: pip install poetry.
Agregar una dependencia
Add the dependency to the [tool.poetry.dependencies] section of pyproject.toml. Make sure to specify an exact version. Then, run the following command: poetry lock --no-update.
Actualizar una dependencia de nivel superior
Update the dependency’s version in the [tool.poetry.dependencies] section of pyproject.toml. Then, run the following command: poetry lock --no-update.