Documentación de construcción¶
Antes de realizar cualquier cambio en la documentación de BeeWare, es útil confirmar que se puede construir la documentación existente.
Antes de crear la documentación, y tener una configura de un entorno de desarrollo.
Debes tener un intérprete de Python 3.13 instalado y
disponible en su ruta (p,ej., python3.13 debe iniciar un
intérprete 3.13) de Python.
BeeWare utiliza tox para construir la documentación. Las
instrucciones de tox siguientes deben ser ejecutadas desde el mismo lugar que
el archivo tox.ini, el cual está dentro del directorio raíz del proyecto.
Vista previa en directo de la documentación¶
Para facilitar la edición rápida de la documentación, BeeWare dispone de un modo de «vista previa en directo».
¡La vista previa en directo se generará con advertencias!
El servidor en vivo está disponible para iterar sobre las actualizaciones de tu
documentación. Mientras estás en el proceso de actualizar cosas, puedes
introducir una incidencia de marcado. Las incidencias consideradas como
ADVERTENCIA harán que la compilación estándar falle, sin embargo, el servidor
en vivo está configurado para indicar advertencias en la salida de la consola,
mientras continúa la compilación. Esto le permite iterar sin necesidad de
reiniciar la vista previa en directo.
Un WARNING es diferente de un ERROR. Si introduce una incidencia que se
considera un ERROR, el servicio en directo fallará, y será necesario
reiniciarlo. No se reiniciará hasta que la incidencia de WARNING se resuelva.
Para iniciar el servidor en directo:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Esto creará la documentación, iniciará un servidor web para servir la documentación, y vigilará el sistema de archivos para detectar cualquier cambio en el origen de la documentación.
Una vez iniciado el servidor, verá algo como lo siguiente en la salida de la consola:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Abre un navegador, y ve a la URL proporcionada. Ahora puedes empezar a iterar sobre la documentación. Si se detecta un cambio, la documentación será reconstruida y cualquier navegador que vea la página modificada se recargada automáticamente.
/// nota | docs-live es un paso inicial
Ejecuta docs-live para funcionar con el servidor en directo está pensado para
la iteración inicial. Tú debes ejecutar siempre una compilación local antes de
enviar un pull request.
///
Construcción local¶
Una vez que hayas terminado de iterar, tendrás que hacer una compilación local de la documentación. Este proceso de compilación está diseñado para fallar si hay algún problema de marcado. Esto le permite detectar cualquier cosa que habría perdido con el servidor en directo.
Generar de una compilación local¶
Para generar una compilación local:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
La salida de esta compilación estará en el directorio _build en la raíz del
proyecto.
Generar una compilación local traducida¶
La documentación de BeeWare está traducida a varios idiomas. Las actualizaciones de la documentación en inglés pueden provocar incidencias en las versiones en otros idiomas. Es importante verificar que todas las versiones funcionan antes de enviar un pull request.
Para generar una compilación de todas las traducciones disponibles:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
El resultado de la compilación de cada idioma estará en el directorio asociado
_build/html/<languagecode>, donde <languagecode> es el código de idioma de
dos o cinco caracteres asociado al idioma específico (p.ej., fr para el
francés, it para el italiano, etc.).
Si encuentra una incidencia con una sola compilación, puede ejecutar esa
compilación separadamente ejecutando tox -e docs-<languagecode>. Por ejemplo,
para compilar solo la documentación en francés, ejecute:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
La salida de una compilación en un solo idioma estará en el directorio _build.
Documentación¶
El proceso de compilación identificará los problemas de Markdown, pero BeeWare realiza algunas comprobaciones adicionales de estilo y formato, conocidas como "hilado". Para ejecutar las comprobaciones de hilado:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Esto validará la documentación que no contiene:
- hiperenlaces muertos
- palabras mal escritas
Si se identifica un deletreo de palabra válida como mal escrita, añádala a la
lista de docs/spelling_wordlist. Esto añadirá la palabra al diccionario del
corrector ortográfico. Al añadir a este listado, recuerda:
- Preferimos la deletreo estadounidense, con algunas libertades para el coloquialismo específico de la programación (p.ej., "apps") y la verborrea de los sustantivos (p.ej., "scrollable")
- Cualquier referencia a un nombre de producto utilizaría la capitalización preferida del producto. (p.ej., “macOS”, “GTK”, “pytest”, “Pygame”, “PyScript”).
- Si un término se utiliza «como código», debe citarse como un literal (
como esto) en lugar de ser añadido al diccionario.
Una vez que hayas creado correctamente los documentos, estarás listo para escribir la documentación.