Documentación de la 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, configura un entorno de desarrollo.
Usted debe tener un intérprete de Python 3.13 instalado
y disponible en su ruta (es decir, python3.13 debe
iniciar un intérprete de Python 3.13).
{{ nombre_formal }} utiliza tox para construir la documentación. Los
siguientes comandos tox deben ejecutarse desde la misma ubicación que el
archivo tox.ini, que se encuentra en el directorio raíz del proyecto.
Vista previa de la documentación en directo¶
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 vivo se generará con advertencias!
El live serve está disponible para iterar sobre las actualizaciones de tu documentación. Mientras estás en el proceso de actualizar cosas, puedes introducir un problema de marcado. Los problemas considerados como "ADVERTENCIA" harán que la compilación estándar falle, sin embargo, el live serve 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 vivo.
Un WARNING es diferente de un ERROR. Si introduce un problema que se
considera un ERROR, el servicio en directo fallará y será necesario
reiniciarlo. No se reiniciará hasta que se resuelva el problema WARNING.
Para iniciar el servidor en vivo:
(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/
Abra un navegador y vaya a la URL indicada. Ahora puede empezar a iterar sobre la documentación. Si se detecta un cambio, la documentación se reconstruirá y cualquier navegador que vea la página modificada se actualizará automáticamente.
docs-live es un primer paso
Ejecutar docs-live para trabajar con el servidor en vivo es para la iteración
inicial. Usted debe siempre ejecutar 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 podría haber perdido con el servidor en vivo.
Generación 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.
Generación de 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 problemas 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 (por ejemplo, fr para el
francés, it para el italiano, etc.).
Si encuentra un problema con una sola compilación, puede ejecutar esa
compilación por separado ejecutando tox -e docs-<languagecode>. Por ejemplo,
para compilar sólo 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 "linting". Para ejecutar las comprobaciones de lint:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Esto validará la documentación no contiene:
- hipervínculos muertos
- palabras mal escritas
Si se identifica una 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 esta lista, recuerde:
- Preferimos la ortografía estadounidense, con algunas libertades para el coloquialismo específico de la programación (por ejemplo, "apps") y la verbosidad de los sustantivos (por ejemplo, "scrollable").
- Cualquier referencia al nombre de un producto debe utilizar la mayúscula preferida del producto. (por ejemplo, "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Si un término se utiliza "como código", debe citarse como literal (
como esto) en lugar de añadirlo al diccionario.
Una vez que hayas creado correctamente los documentos, estarás listo para escribir la documentación.