配对 Jupyter 笔记本和 MyST-NB

配对 Jupyter 笔记本和 MyST-NB#

你将做什么#

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

你将学到什么#

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

  • json 和 markdown 的优缺点

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

你需要什么#

背景#

NumPy 教程](https://github.com/numpy/numpy-tutorials) 以 MyST-NB 笔记本的形式进行审查和执行。内容在这种 markdown 格式中更容易审查。你可以将你的 .ipynb 文件与 NumPy 教程中的内容保持同步。NumPy 教程使用 Jupytext 将你的 .ipynb 文件转换为 MyST Markdown 格式。

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

MyST-NB 笔记本存储在您的磁盘上，采用 markdown 格式。Markdown 格式是一种轻量级标记语言。其关键设计目标是 可读性。缺点是 Markdown 只能存储代码的输入。每次打开笔记本时，您必须执行输入以查看输出。

注意： 你应该使用 common mark markdown 单元格。Jupyter 只渲染 common mark markdown，但 MyST-NB 支持多种 restructured text 指令。这些 Sphinx markdown 指令在 NumPy 教程构建为静态网站时会渲染，但当你在本地或 Binder 上打开时，它们会显示为原始代码。

考虑这两个相同 简单笔记本示例 的版本。你在笔记本中有三样东西：

  1. 一个解释代码的markdown单元格 这段代码计算2+2并打印输出结果。

  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#

当你提交一个 Jupyter 笔记本到 NumPy 教程时，我们（审阅者）会将其转换为 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 配对

动画显示与 Jupyter 经典配对

2. JupyterLab Jupytext 配对

动画显示与 JupyterLab 配对

3. 命令行 Jupytext 配对

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

然后，更新 MyST markdown 或 notebook 文件：

jupytext --sync notebook.ipynb

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

总结#

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

目录