Presentaciones usando Jupyter Notebook.

Imagen tomada de la página jupiter.org

En esta entrada explicaremos paso a paso la forma de crear presentaciones usando Jupyter Notebook. Partiremos de la instalación de todas las herramientas necesarias, hasta llegar a la creación de un archivo *.html, que nos permitirá ver la presentación como una página web desde cualquier navegador usando GitHub.

Jupyter Notebook es un entorno interactivo basado en la web, es un documento JSON. Está formado por una lista de celdas que pueden contener código, texto en Markdown y LaTeX, fórmulas matemáticas y ecuaciones, o también contenido multimedia. Los documentos creados con el Jupyter Notebook pueden exportarse a formatos HTML, PDF, Markdown o Python. Además, es posible trabajar con diferentes lenguajes de programación como: Python, C++, R, Julia, Ruby y SageMath.

La entrada estará dividida en tres partes. La primera corresponde a la instalación del Jupyter Notebook, la segunda a la creación de la presentación, y la tercera a la creación del archivo *.html.

Instalación del Jupyter Notebook

Existen diferentes maneras, las cuales están descritas en la página web de Project Jupyter. Aquí explicaremos una de ellas, la instalación desde Anaconda. Para ello, debemos primero tener instalado Anaconda. La instalación se hará en una distribución de Linux , la cual es muy similar a la instalación en macOS, pero puede que cambie un poco para Windows. En cualquiera de los casos, en la página está la documentación para su instalación.

Imagen tomada de https://www.anaconda.com/products/individual

Con el instalador de Anaconda en la carpeta de descargas procedemos con el siguiente comando en la terminal:

$ bash ~/Descargas/Anaconda3-2020.07-Linux-x86_64.sh

y esperemos … 😴 pero no te duermas, debes estar pendiente de algunas preguntas que se harán durante la instalación. Cuando ésta termine, se cierra y abre la terminal, esto permitirá usar los nuevos paquetes instalados.

En este punto ya puedes hacer varias cosas: verificar las librerías instaladas usando el comando pip freeze, actualizar las librerías usando conda update o empezar a usar el Jupyter Notebook.

Así que iniciemos con nuestra presentación…

Vamos a crear el directorio donde tendremos nuestro primer trabajo usando Jupyter Notebook y Python.

Captura de pantalla de los comandos para crear un directorio y abrir el Jupyter Notebook.

Estos son los comandos a usar:

$ mkdir Jupyter-Notebook-Hello-Word
$ cd Jupyter-Notebook-Hello-Word
$ jupyter notebook

Finalmente, se abrirá esta ventana en el navegador principal:

Ahora, seleccionemos New → Python 3. Esto nos abrirá una hoja de trabajo como la siguiente:

Y, ¿ahora qué? 🙄

Antes de empezar a editar el documento, como nuestro objetivo es hacer presentaciones usando Jupyter Notebook, necesitamos instalar el plugin RISE, que nos permitirá pasar del Notebook a una presentación con diapositivas.

Para instalarlo, desde la terminal ejecutemos la siguiente linea de comandos:

$ conda install -c conda-forge rise

Luego de su instalación aparecerá, al cerrar y abrir la hoja de trabajo, un símbolo de diagrama de barras, así como se ve en la imagen:

Con todo instalado y listo para iniciar, debemos seleccionar en la barra de menú lo siguiente: View →Cell Toolbar →Slideshow. Esto hará que en cada celda del documento aparezca un menú desplegable con las distintas opciones de diapositivas (slides, sub-slides, fragment, skipe and notes).

Para más información sobre el funcionamiento de cada opción de diapositiva se puede consultar la página de documentación para RISE. En general, entenderemos cada tipo de diapositiva como:

• Slides: Dispositivas principales. Para acceder a ellas en la presentación nos moveremos de derecha a izquierda.
• Sub-slides: Son diapositivas relacionadas directamente con su Slide anterior. Para navegar en ellas lo haremos de arriba hacia abajo en la presentación.
• Fragment: Son pedazos de información que aparecerán en la misma diapositiva cada que le demos siguiente.
• Skip y Note: Es información que no aparecerá en la presentación.

En nuestra hoja de trabajo podemos tener celdas con texto y con código. Respectivamente se usan las opciones Markdown y Code sobre cada celda. Luego se elije qué tipo de diapositiva se quiere en cada celda. En nuestro ejemplo, tenemos en la primera celda una diapositiva tipo “slide” y en la segunda celda una diapositiva tipo “fragment”, como se ve en la imagen.

Siguiendo el mismo proceso con cada celda que coloquemos en nuestro proyecto, tendremos como resultado la siguiente presentación:

Para acceder a ella, damos click sobre el ícono del diagrama de barras, y para salir y volver al Notebook haremos click en la ✖ del lado izquierdo. Las flechas nos indican la navegación sobre la presentación.

Cuando la presentación va a ser usada directamente desde el Jupyter Notebook es posible editar el tema de la presentación, el hecho que aparezca la barra lateral o no, entre otras cosas. Todo esto desde la metadata, es decir, se puede editar el archivo JSON al dar View →Edit Notebook Metadata y agregar, por ejemplo:

"rise": {
    "scroll": true,
    "start_slideshow_at": "beginning"
  }

Fragmento agregado al metadata.

🚨 Advertencia : Deben tener mucho cuidado al editar el archivo JSON, ya que, si no son introducidos los parámetros de forma correcta el Notebook no autorizará dicha edición. 🚨

Uso de GitHub Pages

Ya tenemos la presentación 👏 ¿cuál es el siguiente paso?

Esto es opcional, pero te permite compartir tú presentación desde cualuier navegador. Lo que haremos ahora es convertir nuestra presentación en un archivo *.html y usando GitHub haremos de él una página web.

La primera tarea aquí es: “Si aún no tienes una cuenta en GitHub, ⚡ ve lo más rápido posible a abrirla. No puedes seguir la lectura sin ella”.

Con tu cuenta de GitHub lista, tenemos tres caminos para seguir 😱 :

Podemos crear el *.html desde el Notebook seleccionando en la barra de menú File →Download as →Reveal.js slides (.Slides.html). Esto nos creara el archivo siguiente: “Hello Word.Slides.html”.

También podemos crear el archivo *.html usando el siguiente comando:

$ jupyter nbconvert Hello\ World.ipynb --to slides --post serve
--SlidesExporter.reveal_theme=serif      --SlidesExporter.reveal_scroll=True --SlidesExporter.reveal_transition=none

Las instrucciones adicionales, luego de “serve” permiten que las características que usábamos al editar la metadata del Notebook puedan también aplicarse al archivo *.slides.html, ya que estas no se exportan automáticamente al usar la opción anterior.

Otro camino, es clonar el repositorio reveals.js en la carpeta donde tenemos nuestra presentación, usando el siguiente comando:

$ git submodule add https://github.com/hakimel/reveal.js.git reveal.js

y posteriormente convirtiendo nuestro *.ipynb con el comando:

$ jupyter nbconvert --to slides index.ipynb --reveal-prefix=reveal.js

Aquí también podemos agregar instrucciones adicionales de la misma manera que se hizo en el camino dos.

Muchos se preguntaran, ¿cuál es la diferencia entre las tres formas usadas para generar el archivo *.html? La verdad no hay mucha, podríamos pensar en la facilidad y la efectividad. Dicho en otros términos, los dos primeros caminos funcionan en la mayoría de los casos, por lo menos yo no he tenido problema con ellos, y el último puede fallar de vez en cuando.

Si pudieron notar, para la última opción, el archivo del Jupyter Notebook se llama index, esto es muy muy importante, ya que permitirá que el enlace de internet, que generaremos usando GitHub, abra directamente la presentación y no otras cosas. Aunque es posible convertir el archivo sin cambiar su nombre original. El hecho de llamar a nuestro proyecto como index.ipynb es útil si tenemos solo una presentación para dicho repositorio, pero …

🤷‍♀️¿ Y si no es así?🤷‍

En este caso se recomienda, sin importar la opción usada para generar los archivos *.html, colocarlos en carpetas separadas y administrar la página web desde el archivo *.dm que se genera al crear el repositorio en GitHub.

Veamos cómo hacer esto 🧐…

Así que iniciemos, versión 2.0 🚀

Pero no se asusten, no iniciamos de cero. Ya tenemos nuestra presentación en formato *.slides.thml, y tenemos nuestra cuenta de GitHub.

Vamos a crear un repositorio. Yo lo llamaré “Jupyter-Slides-Hola-Mundo” y le diremos que lo cree con archivo Readme.dm incluido. Ahora, nos dirigimos a la consola y clonamos el repositorio:

$ git clone https://github.com/AlejandraTM/Jupyter-Slides-Hola-Mundo.git

El siguiente paso es colocar todos los archivos que vamos a subir a GitHub a esa nueva carpeta en nuestro computador.

Mi consejo: Coloquemos cada presentación en una carpeta. Y con todos los archivos en su lugar escribiremos lo siguientes comandos en la consola:

$ git pull
$ git add *
$ git commit -a -m "Comentario sobre la actualización de los archivos"
$ git push origin master

La primera línea actualiza los cambios hechos desde GitHub a la carpeta clonada, es muy recomendado hacer este proceso siempre, ya que es posible dañar la carpeta guardada en el equipo y es necesario volver a clonarla. La segunda línea agrega todos los archivos de la carpeta, aunque se recomienda agregarlos uno a uno, como en el ejemplo:

$ git add <nombre del archivo>
$ git add <nombre del archivo>
...
$ git add .

La tercera línea, autoriza los cambios acompañados de un comentario. Y la última línea, envía los archivos al repositorio en GitHub. Para más información con respecto a los comandos en GitHub se puede consultar la página: git — la guía sencilla. Finalmente, nuestro repositorio tendrá el siguiente aspecto, con una carpeta por cada archivo de *.thml

Ahora, en ⚙ settings vamos a convertir nuestro repositorio en página web. Nos dirigiremos a GitHub Pages →Source →master →Save

El enlace en el recuadro verde será nuestra página inicial. Finalmente, en el Readme.dm usando Markdown añadiremos los enlaces correspondientes a cada carpeta del repositorio con su respectivo archivo *.html, generando con esto enlaces dentro de la página web.

Nota importante: Para hacer todo este proceso, git debe ser instalado o actualizado en tu computador. Esta página nos brinda información sobre el proceso GIT.

Finalmente nuestra pagina web lucirá así:

No te sientas mal si al abrir tu página aparece con un fondo blanco y con una forma muy simple. Para darle un tema y que luzca distinta se agregó el archivo _config.yml. Para más información pueden visitar Supported themes.

🏆 ¡Terminamos! 🥳

🔗 Les comparto el enlace a mi repositorio con la información usada en esta entrada AlejandraTM / Jupyter-Slides-Hola-Mundo

🔗Les comparto el enlace a la página web del repositorio Aquí.

Quiero agradecer a mi colega y amiga Viviana Márquez quien me enseñó esta herramienta y me motivó a escribir esta entrada.