Comment puis-je ajouter une table des matières à un notebook Jupyter / JupyterLab?

106

La documentation à http://ipython.org/ipython-doc/stable/interactive/notebook.html dit

Vous pouvez fournir une structure conceptuelle pour votre document de calcul dans son ensemble en utilisant différents niveaux d'en-têtes; il y a 6 niveaux disponibles, du niveau 1 (niveau supérieur) au niveau 6 (paragraphe). Ceux-ci peuvent être utilisés plus tard pour construire des tables des matières, etc.

Cependant, je ne trouve nulle part d'instructions sur la façon d'utiliser mes en-têtes hiérarchiques pour créer une telle table des matières. Y a-t-il un moyen de faire cela?

NB: Je serais également intéressé par d'autres types de navigation utilisant des en-têtes de notebook ipython, s'il en existe. Par exemple, sauter en arrière et en avant d'un en-tête à l'autre pour trouver rapidement le début de chaque section, ou masquer (plier) le contenu d'une section entière. Ceci est ma liste de souhaits - mais tout type de navigation serait intéressant. Merci!

user2428107
la source
voir la réponse de @Nikolay ci-dessous pour une solution générale qui fonctionne sur toutes les pages Web .. c'est une excellente réponse.
ihightower
Pour compléter les solutions de notebook Jupyter existantes, j'ai ajouté les instructions JupyterLab ci-dessous.
joelostblom

Réponses:

52

Il existe une nbextension ipython qui construit une table des matières pour un notebook. Il semble ne fournir que la navigation, pas le pliage de section.

Ian
la source
Merci, je suppose que c'est ce à quoi la documentation faisait référence.
user2428107
2
Pour ceux qui veulent l'installer dans jupyter 4, cet article peut aider.
Syrtis Major
9
Juste pour mettre à jour ceci: il existe maintenant une extension nbextensions, qui regroupe de nombreuses extensions et vous permet de les gérer via Jupyter lui-même. Je pense que c'est maintenant le moyen le plus simple d'obtenir ToC2. Et il fournit d'autres extensions pertinentes telles que le pliage de sections. C'est à github.com/ipython-contrib/jupyter_contrib_nbextensions
user2428107
93

Vous pouvez ajouter une table des matières manuellement avec Markdown et HTML. Voici comment j'ai ajouté:

Créez une table des matières en haut de Jupyter Notebook:

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

Ajoutez des ancres html dans tout le corps:

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

code blocks...

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

code blocks...

Ce n'est peut-être pas la meilleure approche, mais cela fonctionne. J'espère que cela t'aides.

Matt Dancho
la source
15
Cela ne fonctionne plus pour moi, mais une approche similaire fonctionne .
joelostblom
2
également la même "approche similaire" que celle-ci: stackoverflow.com/questions/5319754/… tl; dr: utilisation <a name="pookie"></a>pour l'ancre et pour l'utilisation du lien:Take me to [pookie](#pookie)
michael
2
Pour tous les titres de vos démarques, notebook ajoute automatiquement des ancres. Vous pouvez cliquer sur le pilcrow (¶) à droite des en-têtes que vous voyez lorsque vous les survolez, pour révéler l'ancre dans la barre d'adresse de votre navigateur. Vous pouvez utiliser cette ancre au lieu d'ajouter manuellement des ancres aux sections de votre démarque. La meilleure chose est également que cela fonctionne à travers les cellules.
aaruja
1
J'ai ce script add_toc.py qui ajoute une cellule de démarque en haut avec une liste de contenu. Une solution pour homme pauvre si vous ne voulez pas installer d'extensions.
user2148414
18

Que diriez-vous d'utiliser un plugin de navigateur qui vous donne un aperçu de N'IMPORTE QUELLE page html. J'ai essayé ce qui suit:

Ils fonctionnent tous les deux assez bien pour les notebooks IPython. J'étais réticent à utiliser les solutions précédentes car elles semblent un peu instables et ont fini par utiliser ces extensions.

Nikolay
la source
1
Très utile! Mais certaines fonctions intégrées auraient tellement de sens - en particulier dans la combinaison avec markdown
dmeu
13

J'ai récemment créé une petite extension de Jupyter nommée jupyter-navbar . Il recherche les en-têtes écrits dans les cellules de démarquage et affiche des liens vers eux dans la barre latérale de manière hiérarchique. La barre latérale est redimensionnable et pliable. Voir la capture d'écran ci-dessous.

Il est facile à installer et tire parti des codes JS et CSS «personnalisés» qui sont exécutés chaque fois qu'un notebook est ouvert, vous n'avez donc pas besoin de l'exécuter manuellement.

entrez la description de l'image ici

Shovalt
la source
1
En effet, il est facile à installer et le code source est également convivial. Beau projet!
Carson
13

Il existe maintenant deux packages qui peuvent être utilisés pour gérer les extensions Jupyter:

  1. jupyter_contrib_nbextensions qui installe les extensions, y compris la table des matières;

  2. jupyter_nbextensions_configurator qui fournit des interfaces utilisateur graphiques pour configurer les nbextensions activées (se charge automatiquement pour chaque notebook) et fournit des contrôles pour configurer les options des nbextensions.

METTRE À JOUR:

À partir des versions récentes de jupyter_contrib_nbextensions, au moins avec, condavous n'avez pas besoin d'installer jupyter_nbextensions_configuratorcar il est installé avec ces extensions.

Sergey Zakharov
la source
10

Instructions pour JupyterLab ToC

Il existe déjà de nombreuses bonnes réponses à cette question, mais elles nécessitent souvent des ajustements pour fonctionner correctement avec les blocs-notes dans JupyterLab. J'ai écrit cette réponse pour détailler les manières possibles d'inclure une ToC dans un ordinateur portable tout en travaillant et en exportant depuis JupyterLab.

En tant que panneau latéral

le extension jupyterlab-toc ajoute la ToC en tant que panneau latéral qui peut numéroter les en-têtes, réduire les sections et être utilisé pour la navigation (voir gif ci-dessous pour une démo). Installez avec la commande suivante

jupyter labextension install @jupyterlab/toc

entrez la description de l'image ici


Dans le cahier comme une cellule

Pour le moment, cela peut être fait manuellement comme dans la réponse de Matt Dancho, ou automatiquement via l' extension toc2 jupyter notebook dans l'interface classique du notebook.

Tout d'abord, installez toc2 dans le cadre du bundle jupyter_contrib_nbextensions :

conda install -c conda-forge jupyter_contrib_nbextensions

Ensuite, lancez JupyterLab, accédez à Help --> Launch Classic Notebooket ouvrez le bloc-notes dans lequel vous souhaitez ajouter la ToC. Cliquez sur le symbole toc2 dans la barre d'outils pour afficher la fenêtre ToC flottante (voir le gif ci-dessous si vous ne le trouvez pas), cliquez sur l'icône d'engrenage et cochez la case "Ajouter une cellule ToC notebook". Enregistrez le bloc-notes et la cellule ToC sera là lorsque vous l'ouvrirez dans JupyterLab. La cellule insérée est une cellule markdown contenant du HTML, elle ne se mettra pas à jour automatiquement.

Les options par défaut du toc2 peuvent être configurées dans l'onglet "Nbextensions" de la page de lancement du notebook classique. Vous pouvez par exemple choisir de numéroter les en-têtes et d'ancrer la ToC en tant que barre latérale (ce qui, personnellement, semble plus propre).

entrez la description de l'image ici


Dans un fichier HTML exporté

nbconvertpeut être utilisé pour exporter des blocs-notes au format HTML en suivant les règles de mise en forme du HTML exporté. L' toc2extension mentionnée ci-dessus ajoute un format d'exportation appelé html_toc, qui peut être utilisé directement avec à nbconvertpartir de la ligne de commande (après l' toc2installation de l' extension):

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

N'oubliez pas que les commandes shell peuvent être ajoutées aux cellules du bloc-notes en les faisant précéder d'un point d'exclamation !, vous pouvez donc coller cette ligne dans la dernière cellule du bloc-notes et toujours avoir un fichier HTML avec une ToC générée lorsque vous cliquez sur "Exécuter toutes les cellules" ( ou quelle que soit la sortie que vous désirez nbconvert). De cette façon, vous pouvez utiliser jupyterlab-tocpour naviguer dans le notebook pendant que vous travaillez, et toujours obtenir des ToC dans la sortie exportée sans avoir à recourir à l'interface classique du notebook (pour les puristes parmi nous).

Notez que la configuration des options toc2 par défaut comme décrit ci-dessus ne changera pas le format de nbconver --to html_toc. Vous devez ouvrir le notebook dans l'interface classique du notebook pour que les métadonnées soient écrites dans le fichier .ipynb (nbconvert lit les métadonnées lors de l'exportation) Alternativement, vous pouvez ajouter les métadonnées manuellement via l'onglet Outils du notebook de la barre latérale JupyterLab, par exemple quelque chose comme:

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

Si vous préférez une approche basée sur l'interface graphique, vous devriez pouvoir ouvrir le bloc-notes classique et cliquer File --> Save as HTML (with ToC) (bien que notez que cet élément de menu n'était pas disponible pour moi).


Les gifs ci-dessus sont liés à partir de la documentation respective des extensions.

joelostblom
la source
Je préfère travailler avec jupyter lab, mais j'avais besoin d'ajouter une table des matières à une sortie HTML de grand cahier. Cela fonctionne parfaitement! Il y avait quelques étapes supplémentaires pour le faire fonctionner: 1. Activez TOC2, par exemple conda install -c conda-forge jupyter_nbextensions_configurator, allez à http://localhost:8888/nbextensions, décochez «compatibilité» et activez «Toc2» 2. Lancez Classical Notebbok, modifiez les paramètres de TOC selon vos besoins et Add TOC to Cell(procédez comme décrit). 3. Ouvrez votre .ipynbfichier et recherchez "toc", copiez les configs toc json et ajoutez-les aux métadonnées à l'aide de l'onglet Outils de Jupyter lab
Alex
6

introduction

Comme @Ian et @Sergey l'ont mentionné, nbextensions est une solution simple. Pour élaborer leur réponse, voici quelques informations supplémentaires.

Qu'est-ce que nbextensions?

Les nbextensions contiennent une collection d'extensions qui ajoutent des fonctionnalités à votre bloc-notes Jupyter.

Par exemple, juste pour citer quelques extensions:

  • Table des matières

  • En-têtes pliables

Installer nbextensions

L'installation peut être effectuée via Conda ou PIP

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

Copier les fichiers js et css

Pour copier les fichiers javascript et css de nbextensions dans le répertoire de recherche du serveur jupyter, procédez comme suit:

jupyter contrib nbextension install --user

Basculer les extensions

Notez que si vous n'êtes pas familier avec le terminal, il serait préférable d'installer le configurateur nbextensions (voir la section suivante)

Vous pouvez activer / désactiver les extensions de votre choix. Comme le mentionne la documentation, la commande générique est:

jupyter nbextension enable <nbextension require path>

Concrètement, pour activer l'extension ToC (Table of Contents), faites:

jupyter nbextension enable toc2/main

Installer l'interface de configuration (facultatif mais utile)

Comme le dit sa documentation, nbextensions_configurator fournit des interfaces de configuration pour nbextensions.

Cela ressemble à ce qui suit: nbextensions configurateurs

Pour l'installer si vous utilisez conda:

conda install -c conda-forge jupyter_nbextensions_configurator

Si vous n'avez pas Conda ou que vous ne souhaitez pas installer via Conda, procédez comme suit:

pip install jupyter_nbextensions_configurator
jupyter nbextensions_configurator enable --user
KeyMaker00
la source
C'est une réponse excellente et détaillée. J'imagine que l'activation toc2/mainest la même que la vérification de "Table of Contents (2)" sur localhost: 8888 / tree # nbextensions_configurator .
flow2k
4

Voici mon approche, aussi maladroite qu'elle soit et disponible dans github :

Mettez dans la toute première cellule de notebook, la cellule d'importation:

from IPythonTOC import IPythonTOC

toc = IPythonTOC()

Quelque part après la cellule d'importation, placez la cellule genTOCEntry mais ne l'exécutez pas encore:

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

print toc.genTOCEntry()

Sous la cellule genTOCEntry`, créez une cellule TOC en tant que cellule de démarquage:

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

#TOC

Au fur et à mesure que le notebook est développé, mettez ce genTOCMarkdownCell avant de commencer une nouvelle section:

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

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

!cat TOCMarkdownCell.txt

!rm TOCMarkdownCell.txt

Déplacez le genTOCMarkdownCell jusqu'au point de votre bloc-notes où vous voulez commencer une nouvelle section et faites en l'argument genTOCMarkdownCell le titre de chaîne de votre nouvelle section, puis exécutez-le. Ajoutez une cellule de démarquage juste après et copiez la sortie de genTOCMarkdownCell dans la cellule de démarque qui commence votre nouvelle section. Ensuite, allez dans la cellule genTOCEntry près du haut de votre ordinateur portable et exécutez-le. Par exemple, si vous ajoutez l'argument à genTOCMarkdownCell comme indiqué ci-dessus et que vous l'exécutez, vous obtenez cette sortie à coller dans la première cellule de démarquage de votre section nouvellement indexée:

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

###Introduction

Ensuite, lorsque vous allez en haut de votre notebook et exécutez genTocEntry, vous obtenez la sortie:

[Introduction](#Introduction)

Copiez cette chaîne de lien et collez-la dans la cellule de démarquage de la table des matières comme suit:

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

#TOC

[Introduction](#Introduction)

Après avoir modifié la cellule de la table des matières pour insérer la chaîne de lien, puis appuyez sur Maj-Entrée, le lien vers votre nouvelle section apparaîtra dans la table des matières de votre bloc-notes sous forme de lien Web et en cliquant dessus, le navigateur sera positionné vers votre nouvelle section.

Une chose que j'oublie souvent est que cliquer sur une ligne dans la table des matières fait sauter le navigateur vers cette cellule mais ne la sélectionne pas. Quelle que soit la cellule active lorsque nous avons cliqué sur le lien TOC est toujours active, donc une flèche vers le bas ou vers le haut ou shift-enter fait référence à la cellule toujours active, et non à la cellule que nous avons obtenue en cliquant sur le lien TOC.

à travers
la source
2

Comme Ian l'a déjà souligné, il existe une extension de table des matières par minrk pour le notebook IPython. J'ai eu du mal à le faire fonctionner et j'ai créé ce notebook IPython qui génère semi-automatiquement les fichiers pour l'extension de table des matières de minrk dans Windows. Il n'utilise pas les commandes ou les liens 'curl', mais écrit les fichiers * .js et * .css directement dans votre répertoire IPython Notebook-profile.

Il y a une section dans le cahier appelée `` Ce que vous devez faire '' - suivez-la et ayez une belle table des matières flottante :)

Voici une version html qui le montre déjà: http://htmlpreview.github.io/?https://github.com/ahambi/140824-TOC/blob/master/A%20floating%20table%20of%20contents.htm

Anna Christine
la source