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 时,它们将显示为原始代码。
考虑这两个相同 **简单的笔记本示例** 的版本。笔记本中有三件事
一个 markdown 单元格,解释代码
This code calculates 2+2 and prints the output.
一个代码单元格,显示代码
x = 2 + 2 print('x = ', x)
代码单元格的输出
x = 4
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 配对
2. JupyterLab Jupytext 配对
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 可以处理配对以使您的工作保持同步。