Как добавить оглавление в записную книжку Jupyter / JupyterLab?

108

В документации на http://ipython.org/ipython-doc/stable/interactive/notebook.html говорится

Вы можете предоставить концептуальную структуру для своего вычислительного документа в целом, используя заголовки разных уровней; доступно 6 уровней, от уровня 1 (верхний уровень) до уровня 6 (параграф). Их можно использовать позже для построения оглавлений и т. Д.

Однако я нигде не могу найти инструкций о том, как использовать мои иерархические заголовки для создания такого оглавления. Есть ли способ сделать это?

NB: Меня также интересовали бы другие виды навигации с использованием заголовков ipython notebook, если таковые существуют. Например, переход назад и вперед от заголовка к заголовку, чтобы быстро найти начало каждого раздела, или скрытие (сворачивание) содержимого всего раздела. Это мой список желаний, но любая навигация была бы интересна. Спасибо!

user2428107
источник
см. ответ @Nikolay ниже, чтобы узнать об общем решении, которое работает на всех веб-страницах .. это отличный ответ.
ihightower
Чтобы дополнить существующие решения для ноутбуков Jupyter, я добавил ниже инструкции JupyterLab .
joelostblom

Ответы:

52

Существует ipython nbextension, которое создает оглавление для записной книжки. Кажется, он обеспечивает только навигацию, а не сворачивание разделов.

Ян
источник
Спасибо, я полагаю, это то, о чем говорилось в документации.
user2428107
2
Этот пост может помочь тем, кто хочет установить его в jupyter 4 .
Syrtis Major
9
Просто чтобы обновить это: теперь существует расширение nbextensions, которое объединяет множество расширений вместе и позволяет вам управлять ими через сам jupyter. Я думаю, что сейчас это самый простой способ получить ToC2. И он обеспечивает другие соответствующие расширения, такие как складывание секций. Это на github.com/ipython-contrib/jupyter_contrib_nbextensions
user2428107,
93

Вы можете добавить оглавление вручную с помощью Markdown и HTML. Вот как я добавляю:

Создайте оглавление в верхней части Jupyter Notebook:

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

Добавьте якоря html по всему телу:

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

code blocks...

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

code blocks...

Возможно, это не лучший подход, но он работает. Надеюсь это поможет.

Мэтт Данчо
источник
15
У меня это больше не работает, но работает аналогичный подход .
joelostblom
2
также такой же «подобный подход», как этот: stackoverflow.com/questions/5319754/… tl; dr: use <a name="pookie"></a>for anchor and for link use:Take me to [pookie](#pookie)
michael
2
Блокнот автоматически добавляет привязки ко всем заголовкам в вашей уценке. Вы можете нажать на значок (¶) справа от заголовков, которые вы видите при наведении на них курсора, чтобы открыть якорь в адресной строке браузера. Вы можете использовать эту привязку вместо того, чтобы вручную добавлять привязки к разделам вашей уценки. Также лучше всего то, что он работает по ячейкам.
aaruja
1
У меня есть сценарий add_toc.py, который добавляет вверху ячейку уценки со списком содержимого. Решение для бедняков, если вы не хотите устанавливать расширения.
user2148414
18

Как насчет использования плагина для браузера, который дает вам обзор ЛЮБОЙ HTML-страницы. Я пробовал следующее:

Оба они очень хорошо работают с ноутбуками IPython. Я не хотел использовать предыдущие решения, поскольку они казались немного нестабильными, и в конечном итоге использовал эти расширения.

Николай
источник
1
Очень полезно! Но некоторые встроенные функции будут иметь такой смысл - особенно в сочетании с
уценкой
13

Недавно я создал небольшое расширение для Jupyter с именем jupyter-navbar . Он ищет заголовки, записанные в ячейках уценки, и отображает ссылки на них на боковой панели в иерархическом порядке. Размер боковой панели можно изменять, и она складывается. См. Снимок экрана ниже.

Его легко установить, и он использует «пользовательские» коды JS и CSS, которые запускаются каждый раз при открытии записной книжки, поэтому вам не нужно запускать его вручную.

введите описание изображения здесь

Шовальт
источник
1
Действительно, его легко установить, и исходный код тоже дружелюбен. Хороший проект!
Carson
13

Теперь есть два пакета, которые можно использовать для обработки расширений Jupyter:

  1. jupyter_contrib_nbextensions, который устанавливает расширения, включая оглавление;

  2. jupyter_nbextensions_configurator, который предоставляет графический пользовательский интерфейс для настройки того, какие nbextensions включены (загружаются автоматически для каждой записной книжки), и предоставляет элементы управления для настройки параметров nbextensions.

ОБНОВИТЬ:

Начиная с последних версий jupyter_contrib_nbextensions, по крайней мере, condaвам не нужно устанавливать, jupyter_nbextensions_configuratorпотому что он устанавливается вместе с этими расширениями.

Сергей Захаров
источник
12

Инструкции JupyterLab ToC

На этот вопрос уже есть много хороших ответов, но они часто требуют настройки для правильной работы с записными книжками в JupyterLab. Я написал этот ответ, чтобы подробно описать возможные способы включения ToC в записную книжку во время работы и экспорта из JupyterLab.

Как боковая панель

Расширение jupyterlab-toc добавляет ToC в качестве боковой панели, которая может нумеровать заголовки, сворачивать разделы и использоваться для навигации (см. Рисунок ниже для демонстрации). Установите с помощью следующей команды

jupyter labextension install @jupyterlab/toc

введите описание изображения здесь


В записной книжке как клетка

В настоящее время это можно сделать либо вручную, как в ответе Мэтта Данчо, либо автоматически с помощью расширения toc2 jupyter notebook. в классическом интерфейсе ноутбука.

Сначала установите toc2 как часть пакета jupyter_contrib_nbextensions :

conda install -c conda-forge jupyter_contrib_nbextensions

Затем запустите JupyterLab, перейдите к Help --> Launch Classic Notebookи откройте записную книжку, в которую вы хотите добавить ToC. Щелкните символ toc2 на панели инструментов, чтобы открыть плавающее окно ToC (см. Гифку ниже, если вы не можете его найти), щелкните значок шестеренки и установите флажок «Добавить ячейку ToC для записной книжки». Сохраните записную книжку, и ячейка ToC будет там, когда вы откроете ее в JupyterLab. Вставленная ячейка представляет собой ячейку уценки с HTML-кодом в ней, она не будет обновляться автоматически.

Параметры toc2 по умолчанию можно настроить на вкладке «Nbextensions» на классической странице запуска записной книжки. Вы можете, например, пронумеровать заголовки и привязать ToC как боковую панель (что, по моему мнению, выглядит чище).

введите описание изображения здесь


В экспортированном HTML-файле

nbconvertможет использоваться для экспорта записных книжек в HTML, следуя правилам форматирования экспортируемого HTML. toc2Расширение уже упоминалось выше , добавляет формат экспорта под названием html_toc, которое можно использовать непосредственно nbconvertиз командной строки (после того , как toc2было установлено расширение):

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

Помните, что команды оболочки могут быть добавлены в ячейки записной книжки, поставив перед ними восклицательный знак !, поэтому вы можете вставить эту строку в последнюю ячейку записной книжки и всегда иметь файл HTML с ToC, сгенерированный при нажатии кнопки «Выполнить все ячейки» ( или любой другой результат, который вам нужен nbconvert). Таким образом, вы можете использоватьjupyterlab-toc для навигации по записной книжке во время работы и по-прежнему получать ToCs в экспортированном выводе, не прибегая к использованию классического интерфейса записной книжки (для пуристов среди нас).

Обратите внимание, что настройка параметров toc2 по умолчанию, как описано выше, не изменит формат файла nbconver --to html_toc. Вам нужно открыть записную книжку в классическом интерфейсе записной книжки, чтобы метаданные были записаны в файл .ipynb (nbconvert считывает метаданные при экспорте). Кроме того, вы можете добавить метаданные вручную через вкладку «Инструменты записной книжки» на боковой панели JupyterLab, например что-то лайк:

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

Если вы предпочитаете подход, основанный на графическом интерфейсе пользователя, у вас должна быть возможность открыть классический блокнот и щелкнуть File --> Save as HTML (with ToC) (хотя обратите внимание, что этот пункт меню был недоступен для меня).


На приведенные выше гифки есть ссылки из соответствующей документации расширений.

Joelostblom
источник
Я предпочитаю работать jupyter lab, но мне нужно было добавить оглавление в большой HTML-вывод записной книжки. Работает безупречно! Были некоторые дополнительные шаги, чтобы заставить его работать: 1. Включите TOC2, например conda install -c conda-forge jupyter_nbextensions_configurator, перейдите http://localhost:8888/nbextensions, снимите флажок «Совместимость» и включите «Toc2» 2. Запустите Classical Notebbok, измените настройки TOC в соответствии с вашими потребностями и Add TOC to Cell(действуйте, как описано). 3. Откройте .ipynbфайл и найдите "toc", скопируйте конфигурации json toc и добавьте их в метаданные, используя вкладку инструментов лаборатории Jupyter
Алекс,
Я не мог заставить расширение toc2 работать в классическом ноутбуке, чтобы добавить ячейку TOC. Однако экспорт записной книжки с помощью nbconvert --to html_tocработал. Формат отличный и добавляет красивое оглавление сбоку, а также номера заголовков.
aimfeld
6

Введение

Как отметили @Ian и @Sergey, nbextensions - простое решение. Чтобы уточнить свой ответ, вот еще несколько сведений.

Что такое nbextensions?

Nbextensions содержит набор расширений, которые добавляют функциональность вашей записной книжке Jupyter.

Например, просто чтобы процитировать несколько расширений:

  • Оглавление

  • Складные заголовки

Установить nbextensions

Установка может производиться через Conda или PIP.

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

Скопируйте файлы js и css

Чтобы скопировать файлы javascript и css nbextensions в каталог поиска сервера jupyter, выполните следующие действия:

jupyter contrib nbextension install --user

Переключить расширения

Обратите внимание: если вы не знакомы с терминалом, лучше установить конфигуратор nbextensions (см. Следующий раздел)

Вы можете включить / отключить расширения по вашему выбору. Как упоминается в документации, общая команда:

jupyter nbextension enable <nbextension require path>

Конкретно, чтобы включить расширение ToC (Table of Contents), выполните:

jupyter nbextension enable toc2/main

Установите интерфейс конфигурации (необязательно, но полезно)

Как сказано в документации, nbextensions_configurator предоставляет интерфейсы конфигурации для nbextensions.

Выглядит это примерно так: конфигураторы nbextensions

Чтобы установить его, если вы используете conda:

conda install -c conda-forge jupyter_nbextensions_configurator

Если у вас нет Conda или вы не хотите устанавливать через Conda, выполните следующие 2 шага:

pip install jupyter_nbextensions_configurator
jupyter nbextensions_configurator enable --user
KeyMaker00
источник
Это отличный и подробный ответ. Я предполагаю, что включение toc2/mainаналогично проверке «Таблицы содержания (2)» на локальном хосте: 8888 / tree # nbextensions_configurator .
flow2k
4

Вот мой подход, неуклюжий и доступный на github :

Поместите в самую первую ячейку записной книжки, ячейку импорта:

from IPythonTOC import IPythonTOC

toc = IPythonTOC()

Где-то после ячейки импорта поместите ячейку genTOCEntry, но пока не запускайте ее:

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

print toc.genTOCEntry()

Под ячейкой genTOCEntry` сделайте ячейку TOC как ячейку уценки:

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

#TOC

По мере разработки ноутбука поместите этот genTOCMarkdownCell перед началом нового раздела:

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

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

!cat TOCMarkdownCell.txt

!rm TOCMarkdownCell.txt

Переместите genTOCMarkdownCell вниз в то место в записной книжке, где вы хотите начать новый раздел, и сделайте аргумент genTOCMarkdownCell заголовком строки для нового раздела, затем запустите его. Добавьте ячейку уценки сразу после нее и скопируйте вывод genTOCMarkdownCell в ячейку уценки, с которой начинается новый раздел. Затем перейдите к ячейке genTOCEntry в верхней части записной книжки и запустите ее. Например, если вы передадите аргумент genTOCMarkdownCell, как показано выше, и запустите его, вы получите этот вывод для вставки в первую ячейку уценки вашего недавно проиндексированного раздела:

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

###Introduction

Затем, когда вы перейдете в верхнюю часть записной книжки и запустите genTocEntry, вы получите результат:

[Introduction](#Introduction)

Скопируйте эту строку ссылки и вставьте ее в ячейку уценки TOC следующим образом:

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

#TOC

[Introduction](#Introduction)

После того как вы отредактируете ячейку оглавления, чтобы вставить строку ссылки, а затем нажмете shift-enter, ссылка на ваш новый раздел появится в вашем оглавлении записной книжки в виде веб-ссылки, и щелчок по ней переместит браузер в ваш новый раздел.

Одна вещь, которую я часто забываю, - это то, что щелчок по строке в оглавлении заставляет браузер переходить к этой ячейке, но не выбирает ее. Какая бы ячейка ни была активна, когда мы щелкнули ссылку оглавления, она все еще активна, поэтому стрелка вниз или вверх или Shift-Enter относится к все еще активной ячейке, а не к ячейке, которую мы получили, щелкнув ссылку оглавления.

вверх и поперек
источник
2

Как уже отмечал Ян, существует расширение оглавления от minrk для IPython Notebook. У меня возникли проблемы с его работой, и я сделал этот блокнот IPython, который полуавтоматически генерирует файлы для расширения оглавления minrk в Windows. Он не использует команды или ссылки curl, а записывает файлы * .js и * .css непосредственно в ваш IPython Notebook-profile-directory.

В записной книжке есть раздел под названием «Что вам нужно сделать» - следите за ним и получите красивое плавающее оглавление :)

Вот html-версия, которая уже показывает это: http://htmlpreview.github.io/?https://github.com/ahambi/140824-TOC/blob/master/A%20floating%20table%20of%20contents.htm

Анна кристина
источник