Добавление или редактирование учебников в виде Jupyter notebooks#

Под doc/source/ В папке дерева SciPy можно найти несколько документов, написанных в формате MyST Markdown. Содержимое этих файлов выполняется при сборке документации SciPy (локально или на CI), и любые выходные данные, сгенерированные выполнением, отображаются в итоговых HTML-файлах. Кроме того, их можно сделать интерактивными на сайте документации SciPy, используя jupyterlite-sphinx расширение.

Если у вас есть документ, написанный в формате Jupyter notebook ( .ipynb файл) и хотели бы отправить его как часть документации SciPy, есть два варианта: вы можете преобразовать его в файл MyST Markdown и работать с .md только файл, или вы можете сопоставить ваш .ipynb файл с .md файл и работать с обоими. Обратите внимание, что .ipynb файлы не должен должен быть отправлен в документацию SciPy.

В этом документе мы рассматриваем преобразование в файл MyST Markdown. Для получения дополнительной информации о MyST-NB, Jupytext и сопряжении блокнотов, вы также можете обратиться к Парный учебник по NumPy Tutorials. Для получения дополнительной информации обратитесь к Документация MyST-NB.

Как преобразовать .ipynb файл в .md файл#

Если вам не нужно сохранять .ipynb файл и хотите работать только с MyST Markdown, выполните следующие шаги.

  1. Установить jupytext инструмент, используя pip install jupytext или conda install jupytext -c conda-forge;

  2. В терминале выполните jupytext notebook.ipynb --to myst, где notebook.ipynb должен быть заменен файлом, который вы хотите преобразовать.

Теперь, полученный .md файл (в формате MyST Markdown) должен содержать преамбулу, подобную приведённой ниже, указывающую, что его содержимое будет выполнено при сборке документации SciPy:

---
jupytext:
   text_representation:
      extension: .md
      format_name: myst
      format_version: 0.13
      jupytext_version: 1.14.0
kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
---

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

Создание интерактивного блокнота#

Если вы хотите включить интерактивность для вашего блокнота при его отображении на сайте документации SciPy, вам нужно добавить следующий фрагмент в начале файла markdown:

```{eval-rst}
.. notebooklite:: .md
   :new_tab: True
```

где .md должно быть заменено на имя файла, с которым вы работаете. Это создаст кнопку, позволяющую пользователям открыть блокнот в новой вкладке и взаимодействовать с ним. См. Тест Бартлетта на равенство дисперсий (и его источник) для примера.

Примечание

Для простоты мы не хотим, чтобы определённые ячейки блокнота были видны в отображаемой документации. Мы можем скрыть их, добавив "jupyterlite_sphinx_strip" в раздел тегов соответствующей метаданной ячейки. Чтобы сделать это в Markdown файле, добавьте следующий фрагмент прямо перед ячейкой, которую хотите скрыть:

+++ {"tags": ["jupyterlite_sphinx_strip"]}

Обратите внимание, что +++ обозначения должны идти парами, окружая ячейку, которую вы хотите скрыть.

Посетите Документация директивы NotebookLite для получения дополнительных деталей и опций.

Открытие файлов MyST Markdown в приложении Jupyter Notebook#

Если у вас есть jupytext установленный инструмент позволяет открывать MyST Markdown .md файлы в приложении Jupyter Notebook и выполнять их, как вы бы делали с .ipynb файл.

Преобразование .rst файлы в MyST Markdown#

Для преобразования reStructuredText (.rst) файл в MyST Markdown (.md), вы можете следовать инструкциям по форматированию выше. Вы также можете использовать такие инструменты, как RST-to-MyST для автоматизации преобразования, но обратите внимание, что может потребоваться проверка, чтобы убедиться в правильности преобразования. В частности, некоторые директивы reStructuredText могут потребовать обертывания в {eval-rst} Директива MyST, как показано ниже:

Some Markdown here

```{eval-rst}
.. some_rest_directive_here::
  :some_option: some_value
```

Some more Markdown here