README

(NONE OF THIS IS ON THE PUBLIC-REPO README. DELETE, ADAPT)

• Rename the base folder to aplsurp-python
• Conda env (previously dinosip-python-web, now renamed to aplsurp-python-web)
• Conda env: I currently just use environment.yml. But maybe requirements.txt will be needed later for CI-based builds on GH
• To build the site: jb build site (or jb clean site first)
• To preview it: open the file site/_build/html/index.html
• To publish: ghp-import -n -p -f --remote origin site/_build/html
• Integrating Ethan's notebooks:
  • See my local clone of Ethan's repo: /home/mayorga/Desktop/DEI/APL/2021_DON_APL-DID-NOW/Python-crashcourse/NCAT_MATE_floats_teaching/
  • Use url encoding to transform the names of the notebook files if they have spaces and other unsafe characters
• Say something about notebooks: Jupyter notebooks vs notebooks in Colab
• Weave the individual lessons (from Carpentry & Pythia) into the notebooks, or as additional notes here next to each notebook

Stuff in Spanish about Jupyter Book that I'm going to cull and translate

From Hackaton OHW en español

Con el Jupyter Book (y muchos sistemas parecidos), uno modifica los archivos "fuente", típicamente en markdown, y luego "genera" los archivos del sitio en sí. Pueden leer sobre esto aquí.

Los archivos fuente (el contenido) se almacenan en el branch principal, main, bajo la carpeta sitio. Los archivos generados del sitio son colocados en el branch gh-pages. En la gran mayoría de los casos no es recomendable editar los archivos en gh-pages manualmente, directamente. Entonces, hay dos workflows recomendados:

• Se corre (build) jupyter book localmente, para confirmar que todo se vea bien. Una vez que esté listo, se empujan los archivos del build al repositorio usando el programa ghp-import, corrido con algo parecido a esto: ghp-import -n -p -f --remote upstream sitio/_build/html. Los archivos fuente en el repositorio son actualizados usando idealmente un pull request. Esto es lo que he estado haciendo hasta ahora.
• Activando un sistema en GitHub que genera (build) el sitio automáticamente cada vez que se envía un pull request. Este sistema también incluye un preview de los cambios propuestos, que es muy útil. Este automatización hace futuras modificaciones mucho más sencillas, especialmente cuando se trata de modificaciones de páginas existentes.

Este mecanismo automático ya está activo. Ahora, al crear un pull request (PR), después de un minuto (mas o menos) verán un enlace como este bajo "Deploy Preview for sage-puppy-e64764 ready!":

Este enlace los llevará a una versión temporal del sitio donde pueden confirmar los cambios propuestos en el PR. Una vez que le hagan "merge" al PR, el sitio será reconstruido automáticamente en gh-pages con los cambios en el PR. Esto toma un par de minutos.

Pueden ver un ejemplo de esto en un PR reciente, como este: #3

Es sencillo editar una página directamente desde el sitio web: en los íconos arriba a la derecha de cada página, presionen el ícono de gihub y luego seleccionen "suggest edit". Esto los lleva a github, con el interfaz de modificación del markdown.

Cuando estén listos a enviar los cambios, por favor seleccionen "Create a new branch for this commit and start a pull request" antes de presionar "Commit changes". Esto nos permitir a otros revisar los cambios antes de aprobarlos.

Hay dos archivos importantes de configuración del sitio:

• _config.yml. Configuraciones básicas del sitio. Raremente tendremos que modificar esto.
• _toc.yml. "Table of Content". Organización de las páginas en el sitio.