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