Contribuir a la documentación

Contribuir a la documentación#

Tus contribuciones son bienvenidas. Hay muchas formas de contribuir a la documentación:

  1. Identificar y corregir errores tipográficos.

  2. Mejorar la descripción de PyDAP y, en general, del modelo DAP.

  3. Recetas. Queremos saber cómo se están usando PyDAP y OPeNDAP, es decir, qué tipo de preguntas o problemas ayudan a resolver y cuáles son los dominios de experiencia.

  4. Demostrar una optimización en los patrones de acceso, por ejemplo una comparativa de rendimiento.

  5. Una URL de OPeNDAP. Queremos aprender más sobre URLs de datos OPeNDAP disponibles y hacerlas accesibles a la comunidad amplia de usuarios de PyDAP. Somos firmes defensores de la democratización de datos y la ciencia abierta, y ambas comienzan haciendo que tus datos sean encontrables.

La documentación se construyó con jupyter-book, que admite distintos tipos de archivos. Aquí usamos rst e ipynb (notebooks ejecutables).

¿Cómo contribuir a la documentación?#

Para agregar o editar la documentación, recomendamos seguir las guías previas sobre control de versiones, forks y ramas. Dicho eso, puedes seguir estos pasos:

  1. Navega al repositorio clonado en tu máquina local.

  2. Crea o activa el entorno conda.

conda env create -f docs/environment.yml
conda activate pydap_docs

Note

Si ya tienes mamba instalado, puedes reemplazar conda por mamba en todos los comandos.

  1. Instala pydap en modo developer, para asegurarte de que todos los notebooks se construyan correctamente. Para instalar en modo de desarrollo, ejecuta:

pip install -e .

  1. Crea una rama nueva, configura su upstream y usa git (consulta los pasos 3 y 4 de contribuir al código).

  2. La documentación ahora está dividida en dos fuentes: una en inglés (la puedes encontrar en docs/en) y otra en español (la puedes encontrar en docs/es). Dependiendo de la versión de la documentación a la que contribuyas, puedes modificar los archivos fuente.

  3. Una vez que hayas hecho cambios en los archivos fuente de la documentación (ya sea en docs/en o docs/es), usa build.sh para limpiar y construir los archivos de documentación html (puede que necesites hacer que build.sh sea ejecutable con chmod +x).

cd docs
chmod +x build.sh
./build.sh

Warning

Muchos ejemplos tutoriales de la documentación requieren autenticación EDL mediante un archivo local .netrc. Asegúrate de tener uno con credenciales válidas. Consulta Authentication.

Dependiendo de cuántos cambios hayas hecho en la documentación, este último paso puede tardar un tiempo. También depende del tipo de archivos agregados a la documentación (ipynb tarda más en construirse).

  1. Una vez terminado el proceso de construcción, puedes inspeccionar los archivos html generados localmente. build.sh crea una redirección en la base de los archivos html construidos. Por lo tanto, para abrir la documentación en inglés ejecuta:

open _build/html/index.html

La redirección significa que la versión en inglés de la documentación es la predeterminada. Para abrir la versión en español, ejecuta:

open _build/html/es/intro.html

Warning

Asegúrate de comprobar que TODOS los notebooks se construyeron correctamente.

Note

La documentación tendrá un selector para alternar manualmente entre las versiones en inglés y español.

  1. Sube todos los cambios y crea un PR. PyDAP sigue la recomendación de mantener los archivos source en main y los archivos build en la rama gh-pages.

Note

No incluyas contraseñas ni tokens. Solo estás enviando archivos source.

  1. Una vez que una persona mantenedora de PyDAP apruebe tu PR, este se fusionará en main. La persona mantenedora de PyDAP puede publicar la documentación y actualizar la rama gh-pages. En términos generales, los pasos para publicar la documentación (es decir, reconstruir la rama gh-pages) están detallados y descritos aquí: https://jupyterbook.org/en/stable/start/publish.html.