Como posso adicionar um índice analítico a um bloco de notas Jupyter / JupyterLab?

106

A documentação em http://ipython.org/ipython-doc/stable/interactive/notebook.html diz

Você pode fornecer uma estrutura conceitual para o seu documento computacional como um todo usando diferentes níveis de cabeçalhos; Existem 6 níveis disponíveis, do nível 1 (nível superior) até o nível 6 (parágrafo). Eles podem ser usados ​​posteriormente para construir índices, etc.

No entanto, não consigo encontrar instruções em qualquer lugar sobre como usar meus títulos hierárquicos para criar tal índice. Existe uma maneira de fazer isso?

NB: Eu também estaria interessado em outros tipos de navegação usando cabeçalhos de notebook ipython, se houver. Por exemplo, pular de um título para outro para encontrar rapidamente o início de cada seção ou ocultar (dobrar) o conteúdo de uma seção inteira. Esta é a minha lista de desejos - mas qualquer tipo de navegação seria de interesse. Obrigado!

user2428107
fonte
veja a resposta de @Nikolay abaixo para uma solução geral que funciona em todas as páginas da web .. esta é uma ótima resposta.
ihightower
Para complementar as soluções de notebook Jupyter existentes, adicionei as instruções do JupyterLab abaixo.
joelostblom

Respostas:

52

Há um ipython nbextension que constrói um índice para um notebook. Parece fornecer apenas navegação, não dobra de seção.

Ian
fonte
Obrigado, presumo que seja a isso que a documentação se refere.
user2428107
2
Para quem deseja instalar no jupyter 4, este post pode ajudar.
Syrtis Major,
9
Só para atualizar isso: agora existe uma extensão nbextensions, que agrupa um monte de extensões juntas e permite que você as gerencie através do próprio jupyter. Acho que agora é a maneira mais fácil de obter o ToC2. E fornece outras extensões relevantes, como dobra de seção. Está em github.com/ipython-contrib/jupyter_contrib_nbextensions
user2428107
93

Você pode adicionar um TOC manualmente com Markdown e HTML. Veja como venho adicionando:

Crie o TOC no topo do Jupyter Notebook:

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

Adicione âncoras html em todo o corpo:

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

code blocks...

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

code blocks...

Pode não ser a melhor abordagem, mas funciona. Espero que isto ajude.

Matt Dancho
fonte
15
Isso não funciona mais para mim, mas uma abordagem semelhante sim .
joelostblom
2
também a mesma "abordagem semelhante" como esta: stackoverflow.com/questions/5319754/… tl; dr: use <a name="pookie"></a>para âncora e para uso de link:Take me to [pookie](#pookie)
michael
2
Para todos os cabeçalhos em suas marcações, o notebook adiciona âncoras automaticamente. Você pode clicar no pilcrow (¶) à direita dos títulos que você vê quando passa o mouse sobre eles, para revelar a âncora na barra de endereço do navegador. Você pode usar esta âncora em vez de adicionar âncoras manualmente às seções de sua redução. Além disso, a melhor coisa é que ele funciona através das células.
aaruja
1
Eu tenho este script add_toc.py que adiciona uma célula de marcação no topo com uma lista de conteúdos. A solução de um homem pobre se você não quiser instalar extensões.
user2148414
18

Que tal usar um plugin do navegador que lhe dá uma visão geral de QUALQUER página html. Eu tentei o seguinte:

Ambos funcionam muito bem para Notebooks IPython. Eu estava relutante em usar as soluções anteriores, pois elas parecem um pouco instáveis ​​e acabei usando essas extensões.

Nikolay
fonte
1
Muito útil! Mas algumas funções integradas fariam muito sentido - especialmente na combinação com markdown
dmeu
13

Recentemente, criei uma pequena extensão para o Jupyter chamada jupyter-navbar . Ele procura cabeçalhos escritos em células de redução e exibe links para eles na barra lateral de maneira hierárquica. A barra lateral é redimensionável e recolhível. Veja a imagem abaixo.

É fácil de instalar e tira proveito dos códigos JS e CSS 'personalizados' que são executados sempre que um notebook é aberto, portanto, você não precisa executá-lo manualmente.

insira a descrição da imagem aqui

Shovalt
fonte
1
Na verdade, é fácil de instalar e o código-fonte também é amigável. Belo projeto!
Carson
13

Existem agora dois pacotes que podem ser usados ​​para lidar com extensões Jupyter:

  1. jupyter_contrib_nbextensions que instala extensões, incluindo índice analítico ;

  2. jupyter_nbextensions_configurator que fornece interfaces gráficas de usuário para configurar quais nbextensions estão habilitadas (carrega automaticamente para cada notebook) e fornece controles para configurar as opções de nbextensions.

ATUALIZAR:

A partir de versões recentes do jupyter_contrib_nbextensions, pelo menos com condavocê não precisa instalar jupyter_nbextensions_configuratorporque ele é instalado junto com essas extensões.

Sergey Zakharov
fonte
10

Instruções do JupyterLab ToC

Já existem muitas respostas boas para essa pergunta, mas muitas vezes exigem ajustes para funcionar corretamente com notebooks no JupyterLab. Escrevi esta resposta para detalhar as maneiras possíveis de incluir um ToC em um bloco de notas ao trabalhar e exportar do JupyterLab.

Como um painel lateral

A extensão jupyterlab-toc adiciona o ToC como um painel lateral que pode numerar títulos, recolher seções e ser usado para navegação (veja uma demonstração no gif abaixo). Instale com o seguinte comando

jupyter labextension install @jupyterlab/toc

insira a descrição da imagem aqui


No caderno como uma célula

No momento, isso pode ser feito manualmente, como na resposta de Matt Dancho, ou automaticamente por meio da extensão toc2 jupyter para notebook na interface do notebook clássico.

Primeiro, instale toc2 como parte do pacote jupyter_contrib_nbextensions :

conda install -c conda-forge jupyter_contrib_nbextensions

Em seguida, inicie o JupyterLab, vá para Help --> Launch Classic Notebooke abra o bloco de notas no qual deseja adicionar o ToC. Clique no símbolo toc2 na barra de ferramentas para abrir a janela ToC flutuante (veja o gif abaixo se você não conseguir encontrá-lo), clique no ícone de engrenagem e marque a caixa "Adicionar célula ToC de notebook". Salve o bloco de notas e a célula ToC estará lá quando você abri-lo no JupyterLab. A célula inserida é uma célula em markdown com html, ela não será atualizada automaticamente.

As opções padrão do toc2 podem ser configuradas na guia "Nbextensions" na página de inicialização do notebook clássico. Você pode, por exemplo, escolher numerar títulos e ancorar o ToC como uma barra lateral (o que eu pessoalmente acho que parece mais limpo).

insira a descrição da imagem aqui


Em um arquivo HTML exportado

nbconvertpode ser usado para exportar blocos de notas para HTML seguindo as regras de como formatar o HTML exportado. A toc2extensão mencionada acima adiciona um formato de exportação chamado html_toc, que pode ser usado diretamente com nbconverta linha de comando (após a toc2extensão ter sido instalada):

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

Lembre-se de que os comandos do shell podem ser adicionados às células do bloco de notas precedendo-os com um ponto de exclamação !, então você pode colocar esta linha na última célula do bloco de notas e sempre ter um arquivo HTML com um ToC gerado quando você clicar em "Executar todas as células" ( ou qualquer saída que você deseja nbconvert). Dessa forma, você pode usarjupyterlab-toc navegar pelo notebook enquanto está trabalhando, e ainda obter ToCs na saída exportada sem ter que recorrer ao uso da interface de notebook clássica (para os puristas entre nós).

Observe que configurar as opções toc2 padrão conforme descrito acima não alterará o formato de nbconver --to html_toc. Você precisa abrir o bloco de notas na interface do bloco de notas clássico para que os metadados sejam gravados no arquivo .ipynb (nbconvert lê os metadados ao exportar). Alternativamente, você pode adicionar os metadados manualmente por meio da guia Ferramentas do Bloco de anotações da barra lateral do JupyterLab, por exemplo, algo gostar:

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

Se você preferir uma abordagem baseada em GUI, deverá ser capaz de abrir o notebook clássico e clicar File --> Save as HTML (with ToC) (embora observe que este item de menu não estava disponível para mim).


Os gifs acima estão vinculados à respectiva documentação das extensões.

joelostblom
fonte
Eu prefiro trabalhar com jupyter lab, mas precisava adicionar um sumário a uma grande saída HTML do notebook. Isso funciona perfeitamente! Houve algumas etapas adicionais para fazê-lo funcionar: 1. Habilite o TOC2, por exemplo conda install -c conda-forge jupyter_nbextensions_configurator, vá para http://localhost:8888/nbextensions, desmarque "compatibilidade" e habilite "Toc2" 2. Inicie o Notebbok clássico, modifique as configurações do TOC de acordo com suas necessidades e Add TOC to Cell(proceda conforme descrito). 3. Abra seu .ipynbarquivo e pesquise "toc", copie as configurações do json toc e adicione aos metadados usando a guia de ferramentas do Jupyter lab
Alex
6

Introdução

Como @Ian e @Sergey mencionaram, nbextensions é uma solução simples. Para elaborar sua resposta, aqui estão mais algumas informações.

O que é nbextensions?

O nbextensions contém uma coleção de extensões que adicionam funcionalidade ao seu bloco de notas Jupyter.

Por exemplo, apenas para citar algumas extensões:

  • Índice

  • Títulos recolhíveis

Instale nbextensions

A instalação pode ser feita através do Conda ou PIP

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

Copiar arquivos js e css

Para copiar os arquivos javascript e css de nbextensions para o diretório de pesquisa do servidor jupyter, faça o seguinte:

jupyter contrib nbextension install --user

Alternar extensões

Observe que se você não estiver familiarizado com o terminal, seria melhor instalar o configurador nbextensions (consulte a próxima seção)

Você pode ativar / desativar as extensões de sua escolha. Como a documentação menciona, o comando genérico é:

jupyter nbextension enable <nbextension require path>

Concretamente, para ativar a extensão ToC (Índice), faça:

jupyter nbextension enable toc2/main

Interface de configuração de instalação (opcional, mas útil)

Como diz sua documentação, nbextensions_configurator fornece interfaces de configuração para nbextensions.

Parece o seguinte: configuradores nbextensions

Para instalá-lo se você usar conda:

conda install -c conda-forge jupyter_nbextensions_configurator

Se você não tem o Conda ou não deseja instalar pelo Conda, execute as 2 etapas a seguir:

pip install jupyter_nbextensions_configurator
jupyter nbextensions_configurator enable --user
KeyMaker00
fonte
Esta é uma resposta excelente e detalhada. Acho que habilitar toc2/mainé o mesmo que marcar o "Índice (2)" no localhost: 8888 / tree # nbextensions_configurator .
flow2k de
4

Aqui está minha abordagem, desajeitada como é e disponível no github :

Coloque na primeira célula do notebook, a célula de importação:

from IPythonTOC import IPythonTOC

toc = IPythonTOC()

Em algum lugar após a célula de importação, coloque a célula genTOCEntry, mas não execute-a ainda:

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

print toc.genTOCEntry()

Abaixo da célula genTOCEntry, faça uma célula TOC como uma célula de marcação:

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

#TOC

Conforme o notebook é desenvolvido, coloque este genTOCMarkdownCell antes de iniciar uma nova seção:

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

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

!cat TOCMarkdownCell.txt

!rm TOCMarkdownCell.txt

Mova o genTOCMarkdownCell para baixo até o ponto em seu bloco de notas onde deseja iniciar uma nova seção e faça o argumento para genTOCMarkdownCell o título da string para sua nova seção e execute-o. Adicione uma célula de redução logo após e copie a saída de genTOCMarkdownCell para a célula de redução que inicia sua nova seção. Em seguida, vá para a célula genTOCEntry perto da parte superior do seu notebook e execute-o. Por exemplo, se você usar o argumento genTOCMarkdownCell conforme mostrado acima e executá-lo, você obterá esta saída para colar na primeira célula de marcação de sua seção recém-indexada:

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

###Introduction

Então, quando você vai para o topo do seu notebook e executa genTocEntry, obtém a saída:

[Introduction](#Introduction)

Copie esta string de link e cole-a na célula de marcação TOC da seguinte maneira:

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

#TOC

[Introduction](#Introduction)

Depois de editar a célula TOC para inserir a string do link e, em seguida, pressionar Shift-Enter, o link para sua nova seção aparecerá no índice do caderno como um link da web e clicar nele posicionará o navegador em sua nova seção.

Uma coisa que sempre esqueço é que clicar em uma linha no sumário faz o navegador pular para essa célula, mas não a seleciona. Qualquer célula que estava ativa quando clicamos no link TOC ainda está ativa, então uma seta para baixo ou para cima ou shift-enter se refere à célula ainda ativa, não à célula que obtivemos clicando no link TOC.

Upandacross
fonte
2

Como Ian já apontou, há uma extensão de índice por minrk para o Notebook IPython. Tive alguns problemas para fazê-lo funcionar e fiz este Notebook IPython que gera semi-automaticamente os arquivos para a extensão de sumário de minrk no Windows. Ele não usa os comandos ou links 'curl', mas grava os arquivos * .js e * .css diretamente no diretório de perfil do Notebook IPython.

Há uma seção no bloco de notas chamada 'O que você precisa fazer' - siga-a e tenha um bom sumário flutuante:)

Aqui está uma versão html que já mostra: http://htmlpreview.github.io/?https://github.com/ahambi/140824-TOC/blob/master/A%20floating%20table%20of%20contents.htm

Anna christine
fonte