Рубрики
Без рубрики

Переосмысление интерактивной документации Юпитера

Первый релиз jupyter notebook был 8 лет назад – под названием ноутбука ipython в то время. Даже если … с меткой Python, OpenSource, DataScience, Jupyter.

Первый релиз jupyter notebook был 8 лет назад – под названием ноутбука ipython в то время. Даже если записные книжки не были изобретены Юпитером; Они были определенно демократизированы этим. Быть введением в систему позволило разработать много изменений в мире данных дата. Объекты теперь часто обнажают богатое представление; от Pandas DataFrames с AS HTML -таблицами, до более поздних Scikit-learn Model .

Сегодня я хочу изучить тему, которая с тех пор не очень развивалась, и я считаю, что может использовать обновление. Доступ к интерактивной документации, когда на сессии Юпитера и тем, чем она может стать. В конце я ссылаюсь на мой нынешний прототип, если вы авантюрны.

Текущая документация IPython и Jupyter содержится в нескольких формах, но в основном имеет одинаковое ограничение. Типичный способ получить помощь – использовать ? оператор. В зависимости от фронта, который вы используете, принесет пейджер, или панель, которая будет отображать некоторую информацию о текущем объекте.

Он может показать некоторую информацию о текущем объекте (подпись, файл, суб/супер -классы) и необработанном документе объекта.

Вы можете прокрутить, но это все, будь то в терминале или ноутбуках.

Сравните его с той же документацией на веб -сайте Numpy.

Слева документация для Numpy при посещении Сайт Numpy Анкет Давайте назовем это «оформленной документацией». Справа от того, что вы получаете в лаборатории Юпитера или в IPython или обычной Python Repl, давайте нанесем эту «документацию справки», поскольку она обычно достигается через идентификатор? или помощь (идентификатор)

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

  • Трудно читать,
  • Нет навигации,
  • Первые директивы не были интерпретированы,
  • Нет встроенных графиков, не визуализована математика.

Также нет доступа к документации, не основанной на докстроении, Нет повествования , Нет учебников , Нет галереи изображений или примеров , нет поиска, нет синтаксического выделения, нет способа взаимодействовать или изменить документацию для тестирования эффектов параметров.

Из -за ограничений Юпитера и IPython отобразить документацию, я считаю, что авторы часто содержится для документирования функций.

Синтаксис в DocStrings часто остается простым для читаемости, эта первая версия часто предпочтительнее:

You can use ``np.einsum('i->', a)`` ...

В более длинной форме, которая превращает ссылку в ссылку при просмотре документации, ее трудно читать, когда показано в качестве справочной документации:

You can use :py:func:`np.einsum('i->', a) ` ...

Это также приводит к длительным обсуждениям о том, какой синтаксис использовать в продвинутых областях, таких как формулы в Docstrings Sympy Анкет

Многие проекты должны внедрить динамические Docstrings; Например, чтобы включить все параметры, которые функция или класс пройдут, используя ** Kwargs (Поиск исходного кода matplotlib для _kwdoc DataFrame реализация).

Это может сделать его относительно трудным для авторов и участников должного поддержания и предоставления комплексных документов.

Я не уверен, что смогу полностью предсказать все побочные эффекты, которые есть на то, как содействие библиотекам пишут документы; Но я полагаю, что есть также большая возможность для инструмента, чтобы помочь там. См., Например, Vélin который пытается автоматически переформатировать и исправить ошибки формата общего Numpydoc и Опечатки – но это предмет будущего поста.

В то время как SPHINX и связанные с ними проекты отлично подходят для предложения HTML -документации, обширное использование тех, кто усложняет интерактивную документацию.

Пока возможно Запустите Sphinx на лету, когда рендеринг Docstrings , большинство функций Sphinx работают только при создании полного проекта, с надлежащей конфигурацией и расширением, и может быть вычислительно интенсивным. Это делает бегущий сфинкс локально непрактичным.

Разделенные веб -сайты часто могут не отражать локально установленную версию библиотек и требовать тщательного связывания, смягчения и повествования вокруг платформы или конкретных функций.

В течение последних нескольких месяцев я работал над переписыванием того, как iPython (и, следовательно, Юпитер) может отображать документацию. Он работает как в контексте терминала (ipython), так и в контексте браузера (Notebook, Jupyterlab, Spyder) с правильным рендерингом и в настоящее время понимает большинство директив; Это можно настроить, чтобы понять любые новые:

Выше (терминальная) документация scipy.polynomial.lagfit , см., как единичные бэктики правильно поняты, и ссылаются на известные параметры, он обнаружил, что `n` неверно, так как он должен иметь двойные бэктики; Обратите внимание на рендеринг математики даже в терминале.

В этом отношении технически это не заботится о том, написан ли DocString в RST или Markdown; Хотя мне нужно реализовать последнюю часть. Я полагаю, что некоторые сопровождающие были бы очень рады использовать Marckdown, синтаксис которого знакомы с большим количеством пользователей.

Он поддерживает навигацию – здесь, в терминале – где нажатие или нажатие Enter по ссылке приведет вас к целевой странице. В приведенном выше GIF вы можете видеть, что многие токены примера кода также автоматически информируются (спасибо jedi ), а также можно нажать, чтобы перейти на соответствующую страницу.

Изображения включены даже в терминал, когда они не встроены, но заменяются кнопкой, чтобы открыть их в предпочтительном просмотре (см. «Открыть» с помощью QuickLook на приведенном выше экране).

В частности, я работаю над рядом других функций:

  • рендеринг повествовательных документов – для чего у меня есть прототип,
  • автоматическая индексация всех фигур и графиков – работает, но сейчас медленна,
  • Правильная перекрестная ссылка и индексация без необходимости в интерсфинсе. Например, это возможно от numpy.linspace Страница, чтобы увидеть все страницы, которые ссылаются на это, или используют numpy.linspace В их примере (см. Предыдущее изображение).

И многие другие, например, показывают график локальных ссылок между функциями, поиском и конфигурации предпочтений. Я думаю, что это также может поддержать многие другие желаемые функции, такие как пользовательские предпочтения (скрыть/показать аннотацию типа, устаревшие директивы и индивидуальное выделение цвета/синтаксиса) – хотя я не начал работать над ними. У меня есть некоторые идеи о том, как это можно использовать для обеспечения переводов.

Прямо сейчас это не так быстро и эффективно, как я хотел бы – хотя это быстрее, чем запускать Sphinx на лету – но требует некоторых заранее обработки времени. И это рухнет во многих местах; Это может сделать большую часть документации Scipy, Numpy, Xarray, Ipython и Scikit-Image.

Я призываю вас подумать о том, какие функции вам не хватает при использовании документации изнутри Юпитера, и дайте мне знать. Я надеюсь, что это может стать хорошим дополнением к Sphinx при консультации с документацией из Юпитера.

На данный момент я отправил Письмо о намерениях Czi Eoss 4 В попытке финансировать часть этой работы, чтобы приземлиться в Ipython, и если вы заинтересованы в соревнованиях или хотите что -то подобное для вашей библиотеки, не стесняйтесь протянуть руку.

Вы можете найти репозиторий На моей учетной записи GitHub , он все еще находится на стадии до Альфа. На мой вкус все еще довольно нестабильно со слишком большим количеством жестко закодированных ценностей, и нуждается в некотором лаке, который считается пригодным для использования для производства. Я сосредоточился на своих усилиях в основном на рендеринге терминала – ноутбук Jupyter или расширение jupyterlab было бы приветствовалось. Поэтому, если вы приключны и хотите работать с края (или даже кровотечения), пожалуйста, не стесняйтесь попробовать и открыть проблемы/запрос на вытягивание.

Это также должно быть лучше задокументировано (каламбур), я надеюсь использовать сам папирус для документирования папируса; Но это должно быть немного более зрелым для этого.

Следите за новостями, я постараюсь объяснить, как это работает более подробно в последующем посте, и обсудим некоторые преимущества (и недостатки), который имеет этот проект.

Оригинал: “https://dev.to/quansightlabs/rethinking-jupyter-interactive-documentation-4okm”