Ctrl+K

将 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 只能存储代码的输入。每次打开笔记本时，都必须执行输入才能看到输出。

注意：您应该使用常见的标记 Markdown 单元格。 Jupyter 仅渲染常见的标记 markdown，但 MyST-NB 支持各种重构文本指令。当 NumPy 教程内置到静态网站中时，这些 Sphinx markdown 指令将呈现，但当您在本地 Jupyter 或Binder中打开时，它们将显示为原始代码。

考虑同一简单笔记本示例的这两个版本。笔记本里有三件事：

  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 格式。您还可以.md在拉取请求中提交 MyST-NB 。为了保持.ipynb和.md同步或配对，您需要 Jupytext。

安装jupytext使用：

pip install jupytext

或者

conda install jupytext -c conda-forge

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

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

1. 经典的Jupyter Jupytext配对

显示与 Jupyter classic 配对的动画

2.JupyterLab Jupytext配对

显示与 JupyterLab 配对的动画

3.命令行Jupytext配对

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

然后，更新 MyST markdown 或笔记本文件：

jupytext --sync notebook.ipynb

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

包起来＃

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

内容