¿Cómo puedo agregar una tabla de contenido a un cuaderno Jupyter / JupyterLab?

106

La documentación en http://ipython.org/ipython-doc/stable/interactive/notebook.html dice

Puede proporcionar una estructura conceptual para su documento computacional como un todo utilizando diferentes niveles de encabezados; hay 6 niveles disponibles, desde el nivel 1 (nivel superior) hasta el nivel 6 (párrafo). Estos se pueden usar más tarde para construir tablas de contenido, etc.

Sin embargo, no puedo encontrar instrucciones en ninguna parte sobre cómo usar mis encabezados jerárquicos para crear dicha tabla de contenido. ¿Hay alguna forma de hacer esto?

NB: También estaría interesado en otros tipos de navegación usando encabezados de cuaderno ipython, si existen. Por ejemplo, saltar hacia atrás y hacia adelante de un título a otro para encontrar rápidamente el inicio de cada sección, u ocultar (plegar) el contenido de una sección completa. Esta es mi lista de deseos, pero cualquier tipo de navegación sería de interés. ¡Gracias!

usuario2428107
fuente
vea la respuesta de @Nikolay a continuación para obtener una solución general que funciona en todas las páginas web ... esta es una gran respuesta.
ihightower
Para complementar las soluciones de portátiles Jupyter existentes, agregué las instrucciones de JupyterLab a continuación.
joelostblom

Respuestas:

52

Existe una nbextension ipython que construye una tabla de contenido para un cuaderno. Parece que solo proporciona navegación, no sección plegable.

Ian
fuente
Gracias, supongo que esto es a lo que se refería la documentación.
user2428107
2
Para quienes quieran instalarlo en jupyter 4, esta publicación puede ayudar.
Syrtis Major
9
Solo para actualizar esto: ahora hay una extensión nbextensions, que agrupa una gran cantidad de extensiones y le permite administrarlas a través de jupyter. Creo que ahora es la forma más fácil de obtener ToC2. Y aporta otras ampliaciones relevantes como el plegado de perfiles. Está en github.com/ipython-contrib/jupyter_contrib_nbextensions
user2428107
93

Puede agregar un TOC manualmente con Markdown y HTML. Así es como he estado agregando:

Cree TOC en la parte superior de Jupyter Notebook:

## TOC:
* [First Bullet Header](#first-bullet)
* [Second Bullet Header](#second-bullet)

Agregue anclas html en todo el cuerpo:

## First Bullet Header <a class="anchor" id="first-bullet"></a>

code blocks...

## Second Bullet Header <a class="anchor" id="second-bullet"></a>

code blocks...

Puede que no sea el mejor enfoque, pero funciona. Espero que esto ayude.

Matt Dancho
fuente
15
Esto ya no me funciona, pero un enfoque similar sí .
joelostblom
2
también el mismo "enfoque similar" que este: stackoverflow.com/questions/5319754/… tl; dr: use<a name="pookie"></a> para el ancla y para el uso del enlace:Take me to [pookie](#pookie)
michael
2
Para todos los títulos en sus rebajas, el cuaderno agrega anclas automáticamente. Puede hacer clic en el pilcrow (¶) a la derecha de los títulos que ve cuando pasa el cursor sobre ellos, para revelar el ancla en la barra de direcciones de su navegador. Puede utilizar este ancla en lugar de agregar anclajes manualmente a las secciones de su rebaja. Además, lo mejor es que funciona en todas las células.
aaruja
1
Tengo este script add_toc.py que agrega una celda de rebaja en la parte superior con una lista de contenidos. La solución de un pobre hombre si no desea instalar extensiones.
usuario2148414
18

¿Qué tal usar un complemento del navegador que le brinde una descripción general de CUALQUIER página html? He probado lo siguiente:

Ambos funcionan bastante bien para los portátiles IPython. Estaba reacio a usar las soluciones anteriores, ya que parecen un poco inestables y terminé usando estas extensiones.

Nikolay
fuente
1
¡Muy útil! Pero algunas funciones integradas tendrían mucho sentido, especialmente en la combinación con markdown
dmeu
13

Recientemente creé una pequeña extensión de Jupyter llamada jupyter-navbar . Busca encabezados escritos en celdas de rebajas y muestra enlaces a ellos en la barra lateral de forma jerárquica. La barra lateral es redimensionable y plegable. Vea la captura de pantalla a continuación.

Es fácil de instalar y aprovecha los códigos JS y CSS "personalizados" que se ejecutan cada vez que se abre un cuaderno, por lo que no es necesario ejecutarlo manualmente.

ingrese la descripción de la imagen aquí

Shovalt
fuente
1
De hecho, es fácil de instalar y el código fuente también es amigable. Buen proyecto!
Carson
13

Ahora hay dos paquetes que se pueden usar para manejar extensiones de Jupyter:

  1. jupyter_contrib_nbextensions que instala extensiones, incluida la tabla de contenido;

  2. jupyter_nbextensions_configurator que proporciona interfaces gráficas de usuario para configurar qué nbextensions están habilitadas (se cargan automáticamente para cada portátil) y proporciona controles para configurar las opciones de nbextensions.

ACTUALIZAR:

A partir de versiones recientes de jupyter_contrib_nbextensions, al menos con conda, no es necesario instalarlo jupyter_nbextensions_configuratorporque se instala junto con esas extensiones.

Sergey Zakharov
fuente
10

Instrucciones de JupyterLab ToC

Ya hay muchas buenas respuestas a esta pregunta, pero a menudo requieren ajustes para funcionar correctamente con portátiles en JupyterLab. Escribí esta respuesta para detallar las posibles formas de incluir un ToC en un cuaderno mientras trabajaba y exportaba desde JupyterLab.

Como panel lateral

La extensión jupyterlab-toc agrega la ToC como un panel lateral que puede numerar encabezados, contraer secciones y usarse para la navegación (vea el gif a continuación para ver una demostración). Instalar con el siguiente comando

jupyter labextension install @jupyterlab/toc

ingrese la descripción de la imagen aquí


En el cuaderno como una celda

Por el momento, esto se puede hacer manualmente como en la respuesta de Matt Dancho, o automáticamente a través de la extensión del cuaderno toc2 jupyter en la interfaz clásica del portátil.

Primero, instale toc2 como parte del paquete jupyter_contrib_nbextensions :

conda install -c conda-forge jupyter_contrib_nbextensions

Luego, inicie JupyterLab, vaya a Help --> Launch Classic Notebooky abra el cuaderno en el que desea agregar la ToC. Haga clic en el símbolo TOC2 en la barra de herramientas para que aparezca la ventana ToC flotante (vea el gif a continuación si no puede encontrarlo), haga clic en el icono de engranaje y marque la casilla "Agregar celda ToC del cuaderno". Guarde el cuaderno y la celda ToC estará allí cuando lo abra en JupyterLab. La celda insertada es una celda de descuento con html en ella, no se actualizará automáticamente.

Las opciones predeterminadas del toc2 se pueden configurar en la pestaña "Nbextensions" en la página de inicio del portátil clásico. Por ejemplo, puede elegir numerar los títulos y anclar la ToC como una barra lateral (que personalmente creo que se ve más limpia).

ingrese la descripción de la imagen aquí


En un archivo HTML exportado

nbconvertse puede utilizar para exportar cuadernos a HTML siguiendo las reglas de cómo formatear el HTML exportado. La toc2extensión mencionada anteriormente agrega un formato de exportación llamado html_toc, que se puede usar directamente nbconvertdesde la línea de comando (después de que toc2se haya instalado la extensión):

jupyter nbconvert file.ipynb --to html_toc
# Append `--ExtractOutputPreprocessor.enabled=False`
# to get a single html file instead of a separate directory for images

Recuerde que los comandos de shell se pueden agregar a las celdas del cuaderno colocándolos delante de un signo de exclamación !, por lo que puede pegar esta línea en la última celda del cuaderno y siempre tener un archivo HTML con un ToC generado cuando presiona "Ejecutar todas las celdas" ( o cualquier salida que desee nbconvert). De esta manera, podría utilizar jupyterlab-tocpara navegar por el portátil mientras está trabajando y aún obtener ToC en la salida exportada sin tener que recurrir al uso de la interfaz clásica del portátil (para los puristas entre nosotros).

Tenga en cuenta que configurar las opciones predeterminadas de toc2 como se describe anteriormente, no cambiará el formato de nbconver --to html_toc. Debe abrir el cuaderno en la interfaz clásica del cuaderno para que los metadatos se escriban en el archivo .ipynb (nbconvert lee los metadatos al exportar) Alternativamente, puede agregar los metadatos manualmente a través de la pestaña Herramientas del cuaderno de la barra lateral de JupyterLab, por ejemplo, algo me gusta:

    "toc": {
        "number_sections": false,
        "sideBar": true
    }

Si prefiere un enfoque basado en GUI, debería poder abrir el cuaderno clásico y hacer clic File --> Save as HTML (with ToC) (aunque tenga en cuenta que este elemento de menú no estaba disponible para mí).


Los gifs de arriba están vinculados a la documentación respectiva de las extensiones.

joelostblom
fuente
Prefiero trabajar con jupyter lab, pero necesitaba agregar una tabla de contenido a la salida HTML de un cuaderno grande. ¡Esto funciona perfectamente! Hubo algunos pasos adicionales para que funcione: 1. Habilite TOC2, por ejemplo conda install -c conda-forge jupyter_nbextensions_configurator, vaya a http://localhost:8888/nbextensions, desmarque "compatibilidad" y habilite "Toc2". 2. Inicie Classical Notebbok, modifique la configuración de TOC según sus necesidades y Add TOC to Cell(proceda como se describe). 3. Abra su .ipynbarchivo y busque "toc", copie las configuraciones de json toc y agréguelas a los metadatos usando la pestaña de herramientas del laboratorio
Alex
6

Introducción

Como han mencionado @Ian y @Sergey, nbextensions es una solución simple. Para elaborar su respuesta, aquí hay algo más de información.

¿Qué es nbextensions?

Nbextensions contiene una colección de extensiones que agregan funcionalidad a su cuaderno Jupyter.

Por ejemplo, solo para citar algunas extensiones:

  • Tabla de contenido

  • Encabezados plegables

Instalar nbextensions

La instalación se puede realizar a través de Conda o PIP

# If conda:
conda install -c conda-forge jupyter_contrib_nbextensions
# or with pip:
pip install jupyter_contrib_nbextensions

Copiar archivos js y css

Para copiar los archivos javascript y css de nbextensions en el directorio de búsqueda del servidor jupyter, haga lo siguiente:

jupyter contrib nbextension install --user

Alternar extensiones

Tenga en cuenta que si no está familiarizado con el terminal, sería mejor instalar el configurador nbextensions (ver la siguiente sección)

Puede habilitar / deshabilitar las extensiones de su elección. Como menciona la documentación, el comando genérico es:

jupyter nbextension enable <nbextension require path>

Concretamente, para habilitar la extensión ToC (Tabla de contenido), haga lo siguiente:

jupyter nbextension enable toc2/main

Instalar la interfaz de configuración (opcional pero útil)

Como dice su documentación, nbextensions_configurator proporciona interfaces de configuración para nbextensions.

Se parece a lo siguiente: Configuradores de nbextensions

Para instalarlo si usa conda:

conda install -c conda-forge jupyter_nbextensions_configurator

Si no tiene Conda o no desea instalar a través de Conda, siga los siguientes 2 pasos:

pip install jupyter_nbextensions_configurator
jupyter nbextensions_configurator enable --user
KeyMaker00
fuente
Esta es una respuesta excelente y detallada. Supongo que habilitar toc2/maines lo mismo que verificar "Tabla de contenido (2)" en localhost: 8888 / tree # nbextensions_configurator .
flow2k
4

Aquí está mi enfoque, aunque torpe y disponible en github :

Coloque la primera celda del cuaderno, la celda de importación:

from IPythonTOC import IPythonTOC

toc = IPythonTOC()

En algún lugar después de la celda de importación, coloque la celda genTOCEntry pero no la ejecute todavía:

''' if you called toc.genTOCMarkdownCell before running this cell, 
the title has been set in the class '''

print toc.genTOCEntry()

Debajo de la celda genTOCEntry`, cree una celda TOC como celda de rebaja:

<a id='TOC'></a>

#TOC

A medida que se desarrolla el portátil, coloque este genTOCMarkdownCell antes de comenzar una nueva sección:

with open('TOCMarkdownCell.txt', 'w') as outfile:

    outfile.write(toc.genTOCMarkdownCell('Introduction'))

!cat TOCMarkdownCell.txt

!rm TOCMarkdownCell.txt

Mueva genTOCMarkdownCell hasta el punto en su cuaderno donde desea comenzar una nueva sección y haga el argumento para genTOCMarkdownCell el título de la cadena para su nueva sección y luego ejecútelo. Agregue una celda de rebajas justo después y copie el resultado de genTOCMarkdownCell en la celda de rebajas que inicia su nueva sección. Luego vaya a la celda genTOCEntry cerca de la parte superior de su computadora portátil y ejecútela. Por ejemplo, si crea el argumento para genTOCMarkdownCell como se muestra arriba y lo ejecuta, obtendrá esta salida para pegarla en la primera celda de rebaja de su sección recién indexada:

<a id='Introduction'></a>

###Introduction

Luego, cuando va a la parte superior de su cuaderno y ejecuta genTocEntry, obtiene el resultado:

[Introduction](#Introduction)

Copie esta cadena de enlace y péguela en la celda de descuento de TOC de la siguiente manera:

<a id='TOC'></a>

#TOC

[Introduction](#Introduction)

Después de editar la celda TOC para insertar la cadena de enlace y luego presionar shift-enter, el enlace a su nueva sección aparecerá en la Tabla de contenido de su cuaderno como un enlace web y al hacer clic en él, el navegador se ubicará en su nueva sección.

Una cosa que a menudo olvido es que al hacer clic en una línea en la tabla de contenido, el navegador salta a esa celda pero no la selecciona. Cualquiera que sea la celda que estaba activa cuando hicimos clic en el enlace TOC todavía está activa, por lo que una flecha hacia abajo o hacia arriba o shift-enter se refiere a la celda aún activa, no a la celda que obtuvimos al hacer clic en el enlace TOC.

cruzando
fuente
2

Como ya señaló Ian, hay una extensión de tabla de contenido de minrk para el IPython Notebook. Tuve algunos problemas para que funcionara e hice este IPython Notebook que genera semiautomáticamente los archivos para la extensión de la tabla de contenido de minrk en Windows. No utiliza los comandos o enlaces 'curl', pero escribe los archivos * .js y * .css directamente en su directorio IPython Notebook-profile-.

Hay una sección en el cuaderno llamada 'Lo que debe hacer' ; sígala y tenga una buena tabla de contenido flotante :)

Aquí hay una versión html que ya la muestra: http://htmlpreview.github.io/?https://github.com/ahambi/140824-TOC/blob/master/A%20floating%20table%20of%20contents.htm

Anna Christine
fuente