将 Jupyter 笔记本和 MyST-NB 配对

将 Jupyter 笔记本和 MyST-NB 配对#

您将做什么#

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

您将学到什么#

  • Jupyter 的 json 格式和 MyST-NB 的 markdown 格式之间的区别

  • json 和 markdown 的优点和缺点

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

您需要什么#

背景#

NumPy 教程作为 MyST-NB 笔记本进行审查和执行。在此 markdown 格式中，内容更容易审查。您可以将 .ipynb 与 NumPy 教程上的内容保持同步。NumPy 教程使用 Jupytext 将 .ipynb 文件转换为 MyST Markdown 格式。

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

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

注意：您应该使用 common mark markdown 单元格。Jupyter 只渲染 common mark markdown，但 MyST-NB 支持各种结构化文本指令。当 NumPy 教程被构建成一个静态网站时，这些 Sphinx markdown 指令将渲染，但在本地或在 Binder 上使用 Jupyter 打开时，它们将显示为原始代码。

考虑同一个 **简单笔记本示例** 的这两个版本。笔记本中包含三件事

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

  2. 一个代码单元格，用于显示代码

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

  3. 代码单元格的输出

    x = 4

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

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

x =  4

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

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。

将您的笔记本文件 .ipynb 和 .md 配对#

当您向 NumPy 教程提交 Jupyter 笔记本时，我们将（审阅者）将其转换为 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 或笔记本文件

jupytext --sync notebook.ipynb

注意：安装了 Jupytext 后，经典 Jupyter 界面将自动将 MyST 文件打开为笔记本。在 JupyterLab 中，您可以右键单击并选择“使用打开 -> 笔记本”以将其打开为笔记本。代码单元格的输出仅保存在 .ipynb 文件中。

总结#

在本教程中，您看到了用于创建 Jupyter 笔记本的 json .ipynb 和 MyST-NB .md 原始代码。您可以使用这两种格式创建教程。现在，您可以使用 VIM 或 emacs 等简单文本编辑器工作，或者继续在浏览器中构建笔记本。Jupytext 可以处理配对，以使您的工作保持同步。

内容