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、JupyterLab 或命令行中配对这两种格式

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 文件中。

总结#

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