diff --git a/docs/es/docs/contributing.md b/docs/es/docs/contributing.md new file mode 100644 index 000000000..cefdbe57d --- /dev/null +++ b/docs/es/docs/contributing.md @@ -0,0 +1,447 @@ +# Desarrollo - Contribuyendo + +En primer lugar, es posible que desee ver las formas básicas de [ayudar a FastAPI y obtener ayuda](help-fastapi.md){.internal-link target=_blank}. + +## Desarrollando + +Si ya clonaste el repositorio fastapi y quieres adentrarte en el código, aquí hay algunas pautas para configurar su entorno. + +### Entorno virtual con `venv` + +Puede crear un entorno local virtual aislado en un directorio utilizando el módulo `venv` de Python. Hagamos esto en el repositorio clonado (donde está `requirements.txt`): + +
+ +```console +$ python -m venv env +``` + +
+ +Eso creará un directorio `./env/` con los binarios de Python, y luego podrá instalar paquetes para ese entorno local. + +### Activar el entorno + +Activa el nuevo entorno con: + +=== "Linux, macOS" + +
+ + ```console + $ source ./env/bin/activate + ``` + +
+ +=== "Windows PowerShell" + +
+ + ```console + $ .\env\Scripts\Activate.ps1 + ``` + +
+ +=== "Windows Bash" + + O si usas Bash para Windows (por ejemplo, Git Bash): + +
+ + ```console + $ source ./env/Scripts/activate + ``` + +
+ +Para verificar que funcionó, usa: + +=== "Linux, macOS, Windows Bash" + +
+ + ```console + $ which pip + + some/directory/fastapi/env/bin/pip + ``` + +
+ +=== "Windows PowerShell" + +
+ + ```console + $ Get-Command pip + + some/directory/fastapi/env/bin/pip + ``` + +
+ +Si muestra el binario `pip` en `env/bin/pip`, entonces funcionó. 🎉 + +Asegúrate de tener la última versión de pip en su entorno local para evitar errores en los siguientes pasos: + +
+ +```console +$ python -m pip install --upgrade pip + +---> 100% +``` + +
+ +!!! tip "Consejo" + Cada vez que instales un nuevo paquete con `pip` en ese entorno, activa el entorno nuevamente. + + Esto asegura que si usas un programa de la terminal instalado por ese paquete, usa el de tu entorno local y no cualquier otro que pueda instalarse globalmente. + +### Instalar requerimientos utilizando pip + +Después de activar el entorno como se describe arriba: + +
+ +```console +$ pip install -r requirements.txt + +---> 100% +``` + +
+ +Esto instalará todas las dependencias y tu FastAPI local en tu entorno local. + +### Utilizando tu FastAPI local + +Si creas un archivo Python que importa y usa FastAPI, y lo ejecutas con Python desde tu entorno local, usará tu código fuente local clonado de FastAPI. + +Y si actualizas ese código fuente local de FastAPI cuando vuelvas a ejecutar ese archivo Python, utilizará la versión nueva de FastAPI que acabas de editar. + +De esa manera, no tendrás que "instalar" tu versión local para poder probar cada cambio. + +!!! note "Detalles Técnicos" + Esto solo sucede cuando realizas la instalación utilizando el `requirements.txt` incluido en lugar de ejecutar `pip install fastapi` directamente. + + Esto se debe a que dentro del archivo `requirements.txt`, la versión local de FastAPI está marcada para instalarse en modo "editable", con la opción `-e`. + +### Formatear el código + +Hay un script que puedes ejecutar y que formateará y limpiará todo tu código: + +
+ +```console +$ bash scripts/format.sh +``` + +
+ +También ordenará automáticamente todas tus importaciones. + +Para ordenarlos correctamente, necesitas tener FastAPI instalado localmente en tu entorno, con el comando de la sección anterior usando `-e`. + +## Documentación + +Primero, asegúrese de configurar su entorno como se describe anteriormente, eso instalará todos los requisitos. + +### Documentación en vivo + +Durante el desarrollo local, hay un script que construye el sitio y verifica si hay cambios, recargando en vivo: + +
+ +```console +$ python ./scripts/docs.py live + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +Servirá la documentación en `http://127.0.0.1:8008`. + +De esa manera, puedes editar los archivos de documentación/código fuente y ver los cambios en vivo. + +!!! tip "Consejo" + Alternativamente, puedes realizar los mismos pasos que los scripts realizan manualmente. + + Ve al directorio de idiomas, para los documentos principales en inglés en `docs/en/`: + + ```console + $ cd docs/en/ + ``` + + Luego ejecuta `mkdocs` en ese directorio: + + ```console + $ mkdocs serve --dev-addr 8008 + ``` + +#### Typer CLI (opcional) + +Las instrucciones aquí te muestran cómo utilizar el script en `./scripts/docs.py` directamente con el programa `python`. + +Pero también puedes usar Typer CLI y obtendrás el autocompletado en tu terminal para ver los comandos después de instalar el completamiento. + +Si instalas Typer CLI, puedes instalar el completamiento con: + +
+ +```console +$ typer --install-completion + +zsh completion installed in /home/user/.bashrc. +Completion will take effect once you restart the terminal. +``` + +
+ +### Estructura de la Documentación + +La documentación utiliza MkDocs. + +Y hay herramientas/scripts adicionales para manejar las traducciones en `./scripts/docs.py`. + +!!! tip "Consejo" + No necesitas ver el código en `./scripts/docs.py`, solo úsalo en la línea de comando. + +Toda la documentación está en formato Markdown en el directorio. `./docs/en/`. + +Muchos de los tutoriales tienen bloques de código. + +En la mayoría de los casos, estos bloques de código son aplicaciones reales completas que se pueden ejecutar tal cual. + +De hecho, esos bloques de código no están escritos dentro de Markdown, son archivos de Python en el directorio `./docs_src/`. + +Y esos archivos Python se incluyen/inyectan en la documentación cuando se genera el sitio. + +### Documentación para las pruebas + +La mayoría de las pruebas en realidad se ejecutan con los archivos de código fuente de ejemplo en la documentación. + +Esto ayuda a garantizar que: + +*La documentación está actualizada. +* Los ejemplos de documentación se pueden ejecutar tal cual. +* La mayoría de las características están cubiertas por la documentación, garantizado por la cobertura de las pruebas. + +#### Aplicaciones y documentación al mismo tiempo + +Si ejecuta los ejemplos con, ej.: + +
+ +```console +$ uvicorn tutorial001:app --reload + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +como Uvicorn utilizará por defecto el puerto `8000`, la documentación sobre el puerto `8008` no entrará en conflicto. + +### Traducciones + +¡Se agradece MUCHO la ayuda con las traducciones! Y no se puede hacer sin la ayuda de la comunidad. 🌎 🚀 + +Estos son los pasos para ayudar con las traducciones. + +#### Consejos y recomendaciones + +* Verifica los pull requests existentes actualmente para tu idioma. Puedes filtrar los pull requests por aquellas que tienen la etiqueta para tu idioma. Por ejemplo, para español, la etiqueta es `lang-es`. + +* Revisa esos pull request, solicitando cambios o aprobándolos. Para los idiomas que no hablo, esperaré a que otros revisen la traducción antes de fusionarlos. + +!!! tip "Consejo" + Puedes agregar comentarios con sugerencias de cambios a los pull requests existentes. + + Consulta las documentación sobre agregar una revisión de pull request para aprobar o solicitar cambios. + +* Comprueba si hay una Discusión de GitHub para coordinar las traducciones de tu idioma. Puedes suscribirte y, cuando haya un nuevo pull request para revisar, se agregará un comentario automático a la discusión. + +* Si traduces páginas, agrega un único pull request por página traducida. Eso hará que sea mucho más fácil para otros revisarlo. + +* Para comprobar el código de 2 letras del idioma que deseas traducir, puedes utilizar la tabla Lista de códigos ISO 639-1. + +#### Idioma existente + +Digamos que deseas traducir una página a un idioma que ya tiene traducciones para algunas páginas, como el Español. + +En el caso del Español, el código de 2 letras es `es`. Entonces, el directorio de traducciones al español se encuentra en `docs/es/`. + +!!! tip "Consejo" + El idioma principal ("oficial") es Inglés, localizado en `docs/en/`. + +Ahora ejecuta el servidor para la documentación en vivo en Español: + +
+ +```console +// Use the command "live" and pass the language code as a CLI argument +$ python ./scripts/docs.py live es + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +!!! tip "Consejo" + Alternativamente, puedes realizar los mismos pasos que los scripts manualmente. + + Vaya al directorio de idiomas, para las traducciones al Español están en `docs/es/`: + + ```console + $ cd docs/es/ + ``` + + Luego ejecuta `mkdocs` en ese directorio: + + ```console + $ mkdocs serve --dev-addr 8008 + ``` + +Ahora puedes ir a http://127.0.0.1:8008 y ver tus cambios en vivo. + +Verás que cada idioma tiene todas las páginas. Pero algunas páginas no están traducidas y tienen un cuadro de información en la parte superior sobre la traducción faltante. + +Ahora digamos que quieres agregar una traducción para la sección [Características](features.md){.internal-link target=_blank}. + +* Copia el fichero en: + +``` +docs/en/docs/features.md +``` + +* Pégalo exactamente en la misma ubicación pero para el idioma que deseas traducir, por ejemplo: + +``` +docs/es/docs/features.md +``` + +!!! tip "Consejo" + Observa que el único cambio en la ruta y el nombre del archivo es el código de idioma, de `en` a `es`. + +Si vas a tu navegador, verás que ahora la documentación muestran tu nueva sección (el cuadro de información en la parte superior desapareció). 🎉 + +Ahora puedes traducirlo todo y ver cómo queda al guardar el archivo. + +#### Idioma nuevo + +Digamos que deseas agregar traducciones para un idioma que aún no está traducido, ni siquiera algunas páginas. + +Supongamos que desea agregar traducciones para Creole y aún no está en la documentación. + +Verificando el enlace de arriba, el código para "Creole" es `ht`. + +El siguiente paso es ejecutar el script para generar un nuevo directorio de traducción: + +
+ +```console +// Use the command new-lang, pass the language code as a CLI argument +$ python ./scripts/docs.py new-lang ht + +Successfully initialized: docs/ht +``` + +
+ +Ahora puedes consultar en tu editor de código el directorio recién creado. `docs/ht/`. + +Ese comando creó un archivo `docs/ht/mkdocs.yml` con una configuración simple que hereda todo de la versión `en`: + +```yaml +INHERIT: ../en/mkdocs.yml +``` + +!!! tip "Consejo" + También puedes simplemente crear ese archivo con ese contenido manualmente. + +Ese comando también creó un archivo dummy `docs/ht/index.md` para la página principal, puedes comenzar traduciendo ese. + +Puede continuar con las instrucciones anteriores para un "Idioma existente" para ese proceso. + +Puedes hacer el primer pull request con estos dos archivos, `docs/ht/mkdocs.yml` y `docs/ht/index.md`. 🎉 + +#### Previsualizar el resultado + +Como ya se mencionó anteriormente, puedes utilizar `./scripts/docs.py` con el comando `live` para obtener una vista previa de los resultados (o `mkdocs serve`). + +Una vez que hayas terminado, también puedes probarlo todo tal como se vería en línea, incluidos todos los demás idiomas. + +Para hacer eso, primero crea todas las documentaciones: + +
+ +```console +// Use the command "build-all", this will take a bit +$ python ./scripts/docs.py build-all + +Building docs for: en +Building docs for: es +Successfully built docs for: es +``` + +
+ +Esto crea todos esos sitios MkDocs independientes para cada idioma, los combina y genera el resultado final en `./site/`. + +Entonces puedes servir eso con el comando `serve`: + +
+ +```console +// Use the command "serve" after running "build-all" +$ python ./scripts/docs.py serve + +Warning: this is a very simple server. For development, use mkdocs serve instead. +This is here only to preview a site with translations already built. +Make sure you run the build-all command first. +Serving at: http://127.0.0.1:8008 +``` + +
+ +#### Consejos y pautas específicas de traducción + +* Traduce sólo los documentos Markdown (`.md`). No traduce los ejemplos de código en `./docs_src`. + +* En bloques de código dentro del documento Markdown, traduce los comentarios ("# un comentario"), pero deje el resto sin cambios. + +* No cambie nada incluido en "``" (código en línea). + +* En líneas que comienzan con `===` o `!!!`, traduce solo la parte ` "... Texto ..."`. Deja el resto sin cambios. + +* Puedes traducir cuadros de información como `!!! warning` con por ejemplo `!!! warning "Alerta"`. Pero no cambies la palabra inmediatamente después de `!!!`, ya que determina el color del cuadro de información. + +* No cambies las rutas en enlaces a imágenes, archivos de código, documentos Markdown. + +* Sin embargo, cuando se traduce un documento de Markdown, las `#hash-parts` en los enlaces a sus encabezados pueden cambiar. Actualiza estos enlaces si es posible. + * Busca dichos enlaces en el documento traducido utilizando la expresión regular `#[^# ]`. + * Busca en todos los documentos ya traducidos a su idioma `su-documento-traducido.md`. Por ejemplo, VS Code tiene una opción "Editar" -> "Buscar en archivos". + * Al traducir un documento, no "traduzcas previamente" `#hash-parts` que enlacen a encabezados en documentos no traducidos. + +## Pruebas + +Existe un script que puedes ejecutar localmente para probar todo el código y generar informes de cobertura en HTML: + +
+ +```console +$ bash scripts/test-cov-html.sh +``` + +
+ +Este comando genera un directorio `./htmlcov/`, si abre el archivo `./htmlcov/index.html` en tu navegador, puedes explorar interactivamente las regiones de código que están cubiertas por las pruebas y observar si hay falta alguna región.