配對 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 函式庫所能建立的任何輸入和輸出。缺點是，在審查 Pull Request 時難以查看和比較筆記本檔案中的變更，因為這意味著審查者只能查看原始的 JSON 檔案。

MyST-NB 筆記本儲存在您的磁碟中，採用 Markdown 格式。Markdown 格式是一種輕量級的標記語言，其主要設計目標是 _可讀性_。缺點是 Markdown 只能儲存程式碼的輸入。每次開啟筆記本時，都必須執行輸入才能看到輸出。

**注意：**您應該使用 CommonMark Markdown 儲存格。Jupyter 只渲染 CommonMark Markdown，但 MyST-NB 支援各種 restructured text 指令。這些 Sphinx Markdown 指令在 NumPy 教學編譯成靜態網站時會被渲染，但在您於本機或 Binder 上使用 Jupyter 開啟時，它們會顯示為原始程式碼。

考慮以下兩個版本的相同 **簡單筆記本範例**。這些筆記本包含三項內容：

  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 格式。您也可以在 Pull Request 中提交 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 檔案中。

總結#

在本教學中，您看到了用於建立 Jupyter 筆記本的 json .ipynb 和 MyST-NB .md 原始碼。您可以使用這兩種格式來建立教學。現在，您可以在 VIM 或 Emacs 等簡單的文字編輯器中工作，或繼續在瀏覽器中建構筆記本。Jupytext 可以處理配對以保持您的工作同步。