在JupyterLab中使用MyST
项目描述
JupyterLab MyST 扩展
使用 MyST Markdown 渲染 Markdown 单元，包括对丰富的前置信息、交互式引用、警告、图编号、选项卡、证明、练习、术语表、卡片和网格的支持！
注意：如果您在寻找基于 jupyterlab-markup 的此存储库版本，请查看
v0 分支。
信息 此扩展由名为
jupyterlab_myst的 Python 包组成，用于服务器扩展，以及名为jupyterlab-myst的 NPM 包，用于前端扩展。
要求
- JupyterLab >= 4.0.0
安装
要安装扩展，请执行
pip install jupyterlab_myst
功能
jupyterlab-myst 是一个功能齐全的技术文档 Markdown 渲染器，从 MyST Markdown 开始。它支持 MyST {eval} 内联角色，便于将代码输出和散文交织在一起。例如，我们可以使用内联表达式来探索 NumPy 数组的属性。
在代码单元格
import numpy as np
array = np.arange(4)
在 Markdown 单元格
Let's consider the following array: {eval}`array`.
We can compute the total: {eval}`array.sum()` and the maximum value is {eval}`array.max()`.
这将内联评估并显示
Let's consider the following array: array([0, 1, 2, 3]).
We can compute the total: 6 and the maximum value is 3.
您还可以与 ipywidgets 一起使用，并在内联文本中进行交互
或者与 matplotlib 一起使用，显示内联火花线
您还可以直接在渲染的 Markdown 中编辑任务列表。
用法
MyST 是 Markdown 的一种风味，它结合了 Markdown 写作的流畅体验和 reStructuredText 的可编程可扩展性。此 JupyterLab 扩展使开发丰富的、计算性的叙述、技术文档和开放的科学研究变得更容易。
执行 🚀
为了便于内联表达式，jupyterlab-myst 定义了一个 jupyterlab-myst:executor 插件。当用户“执行”Markdown 单元时，此插件会将表达式代码片段发送到活动内核。要禁用此功能，请使用以下方法禁用 jupyterlab-myst:executor 插件
jupyter labextension disable jupyterlab-myst:executor
信任 🔎
Jupyter Notebooks 实现了一个基于信任的安全模型。随着内联表达式的添加，Markdown 单元现在在确定某个笔记本是否“受信任”时也被考虑。任何带有内联表达式元数据（带有显示数据）的 Markdown 单元都被视为“不受信任”。与输出一样，如果单元格不被视为受信任，表达式结果将使用安全的渲染器进行渲染。执行笔记本将使每个单元格被视为受信任。
为了便于扩展信任模型，jupyterlab_myst 服务器扩展用 MySTNotebookNotary 替换了来自 nbformat 的 NotebookNotary。此功能可以通过以下方法禁用
jupyter server extension disable jupyterlab-myst
禁用此扩展后，将无法从内联表达式渲染不安全的表达式结果；MySTNotebookNotary 添加了额外的代码，使得可以标记 Markdown 单元为受信任。
卸载
要删除扩展，请执行
pip uninstall jupyterlab_myst
故障排除
如果您看到前端扩展但无法使用，请检查服务器扩展是否启用
jupyter server extension list
如果服务器扩展已安装并启用，但您看不到前端扩展，请检查前端扩展是否已安装
jupyter labextension list
贡献
开发安装
注意：您需要 NodeJS 来构建扩展包。
jlpm 命令是 JupyterLab 随附的 yarn 的固定版本，它随 JupyterLab 一起安装。您可以在以下命令中使用 yarn 或 npm 代替 jlpm。
# Clone the repo to your local environment
# Change directory to the jupyterlab_myst directory
# Install package in development mode
pip install -e ".[test]"
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Server extension must be manually installed in develop mode
jupyter server extension enable jupyterlab_myst
# Rebuild extension Typescript source after making changes
jlpm build
您可以在不同的终端中同时监视源目录并运行 JupyterLab，以监视扩展源的变化并自动重新构建扩展。
# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm watch
# Run JupyterLab in another terminal
jupyter lab
当运行watch命令时，每次保存的更改将立即在本地构建并可供您的JupyterLab运行实例使用。刷新JupyterLab以在浏览器中加载更改（您可能需要等待几秒钟，以便扩展程序重新构建）。
默认情况下，jlpm build命令为该扩展生成源映射，以便使用浏览器开发者工具更容易调试。要为JupyterLab核心扩展也生成源映射，可以运行以下命令
jupyter lab build --minimize=False
开发卸载
# Server extension must be manually disabled in develop mode
jupyter server extension disable jupyterlab_myst
pip uninstall jupyterlab_myst
在开发模式下，您还需要删除由jupyter labextension develop命令创建的符号链接。要找到其位置，可以运行jupyter labextension list以确定labextensions文件夹的位置。然后您可以从该文件夹中删除名为jupyterlab-myst的符号链接。
测试扩展
服务器测试
此扩展使用Pytest进行Python代码测试。
安装测试依赖项（只需安装一次）
pip install -e ".[test]"
# Each time you install the Python package, you need to restore the front-end extension link
jupyter labextension develop . --overwrite
要执行它们，请运行
pytest -vv -r ap --cov jupyterlab_myst
前端测试
此扩展使用Jest进行JavaScript代码测试。
要执行它们，执行
jlpm
jlpm test
集成测试
此扩展使用Playwright进行集成测试（也称为用户级测试）。更准确地说，使用JupyterLab辅助工具Galata来处理在JupyterLab中测试扩展。
更多信息请参阅ui-tests的README。
