配对 Jupyter notebook 和 MyST-NB

配对 Jupyter notebook 和 MyST-NB#

您将进行的操作#

本指南将使 Jupyter notebook 在 .ipynb 和 .md 之间保持同步（或配对）。

您将学到什么#

  • Jupyter 的 JSON 格式和 MyST-NB 的 Markdown 格式之间的区别

  • JSON 和 Markdown 的优点与缺点

  • 如何使 .ipynb 和 .md 文件保持同步

您将需要什么#

背景#

NumPy 教程作为 MyST-NB notebook 进行评审和执行。此 Markdown 格式的内容更易于评审。您可以使您的 .ipynb 文件与 NumPy 教程上的内容保持同步。NumPy 教程使用 Jupytext 将您的 .ipynb 文件转换为 MyST Markdown 格式。

Jupyter notebook 以 JSON 格式存储在您的磁盘上。JSON 格式非常强大，允许您存储 Python 库可以创建的几乎任何输入和输出。缺点是，在评审拉取请求时，很难查看和比较 notebook 文件中做出的更改，因为这意味着评审者只能查看原始 JSON 文件。

MyST-NB notebook 以 Markdown 格式存储在您的磁盘上。Markdown 格式是一种轻量级标记语言。其主要设计目标是可读性。缺点是 Markdown 只能存储您的代码输入。每次打开 notebook 时，都必须执行输入才能看到输出。

注意：您应该使用 CommonMark Markdown 单元格。Jupyter 仅渲染 CommonMark Markdown，但 MyST-NB 支持各种 reStructuredText 指令。这些 Sphinx Markdown 指令在 NumPy 教程构建成静态网站时会渲染，但当您在本地 Jupyter 或 Binder 上打开时，它们将显示为原始代码。

考虑同一简单 notebook 示例的这两个版本。notebook 中有三项内容

  1. 一个 Markdown 单元格，解释代码 This code calculates 2+2 and prints the output.

  2. 一个显示代码的代码单元格

    x = 2 + 2
print('x = ', x)

  3. 代码单元格的输出

    x = 4

简单 notebook 示例
此代码计算 2+2 并打印输出。

x = 2 + 2
print("x = ", x)

x =  4

以下是两个简单 notebook 示例的原始输入并排显示

JSON .ipynb MyST-NB .md 
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This code calculates 2+2 and prints the output"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "x =  4\n"
     ]
    }
   ],
   "source": [
    "x = 2 + 2\n",
    "print('x = ', x)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}

---
jupytext:
  formats: ipynb,md:myst
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.12
    jupytext_version: 1.6.0
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

This code calculates 2+2 and prints the output

```{code-cell} ipython3
x = 2 + 2
print('x = ', x)
```

MyST-NB .md 文件要短得多，但它不会保存输出 4。

配对您的 notebook 文件 .ipynb 和 .md#

当您向 NumPy 教程提交 Jupyter notebook 时，我们（评审者）会将其转换为 MyST-NB 格式。您也可以在拉取请求中提交 MyST-NB .md 文件。要使 .ipynb 和 .md 文件保持同步（或配对），您需要 Jupytext。

使用以下命令安装 jupytext

pip install jupytext

或

conda install jupytext -c conda-forge

安装后，在浏览器中启动您的 jupyter lab 或 jupyter notebook 会话。启动 jupyter lab 时，它会要求您重建以包含 Jupytext 扩展。

您可以在经典 Jupyter、Jupyter Lab 或命令行中配对这两种格式

1. 经典 Jupyter Jupytext 配对

Animation showing pairing with Jupyter classic

2. JupyterLab Jupytext 配对

Animation showing pairing with JupyterLab

3. 命令行 Jupytext 配对

jupytext --set-formats ipynb,myst notebook.ipynb

然后，更新 MyST Markdown 或 notebook 文件

jupytext --sync notebook.ipynb

注意：安装 Jupytext 后，经典 Jupyter 界面将自动以 notebook 形式打开 MyST 文件。在 JupyterLab 中，您可以右键单击并选择“打开方式 -> Notebook”以 notebook 形式打开。您的代码单元格的输出仅保存在 .ipynb 文件中。

总结#

在本教程中，您了解了用于创建 Jupyter notebook 的 JSON .ipynb 和 MyST-NB .md 原始代码。您可以使用这两种格式来创建教程。现在，您可以在简单的文本编辑器（如 VIM 或 Emacs）中工作，或继续在浏览器中构建 notebook。Jupytext 可以处理配对以保持您的工作同步。

目录