将教程添加或编辑为 Jupyter 笔记本#

在 SciPy 树的 doc/source/ 文件夹下，您可以找到一些以 MyST Markdown 格式编写的文档。这些文件中的内容在 SciPy 文档构建时（本地或在 CI 上）执行，并且执行生成的任何输出都会在最终的 HTML 文件中渲染。此外，通过使用 jupyterlite-sphinx 扩展，它们可以在 SciPy 文档网站中实现交互。

如果您有一份以 Jupyter 笔记本格式（`.ipynb` 文件）编写的文档，并希望将其作为 SciPy 文档的一部分提交，则有两种选择：您可以将其转换为 MyST Markdown 文件，只处理一个 `.md` 文件；或者您可以将您的 `.ipynb` 文件与一个 `.md` 文件配对，同时处理两者。请注意，`.ipynb` 文件*不应*提交到 SciPy 文档中。

在本文件中，我们将讨论转换为 MyST Markdown 文件。有关 MyST-NB、Jupytext 和配对笔记本的更多信息，您也可以查阅 NumPy 教程中的配对教程。获取更多信息，请查阅 MyST-NB 文档。

如何将 `.ipynb` 文件转换为 `.md` 文件#

如果您不需要保留 `.ipynb` 文件，只想使用 MyST Markdown，请按照以下步骤操作。

使用 `pip install jupytext` 或 `conda install jupytext -c conda-forge` 安装 jupytext 工具；
在您的终端中，运行 `jupytext notebook.ipynb --to myst`，其中 `notebook.ipynb` 应替换为您要转换的文件。

现在，生成的 `.md` 文件（MyST Markdown 格式）应该包含一个类似下面的序言，表明其内容将在 SciPy 文档构建时执行

---
jupytext:
   text_representation:
      extension: .md
      format_name: myst
      format_version: 0.13
      jupytext_version: 1.14.0
kernelspec:
   display_name: Python 3 (ipykernel)
   language: python
   name: python3
---

您无需编辑此序言，因为它是自动生成的。

链接、格式和图像#

将笔记本转换为 MyST Markdown 文件时，您可能需要调整部分内容以匹配 MyST Markdown 语法。

外部链接： MyST Markdown 使用标准的 Markdown 语法进行链接。例如，`[link text](https://www.example.com)`。
内部链接： 对于内部交叉引用，例如指向 SciPy 类或函数的链接，以及 intersphinx 链接，您可以使用以下语法：`{role}`link text <reference>``，其中 `role` 可以是 `ref`、`class`、`func` 或您在 reST 中使用的任何其他角色。例如，要链接到 `scipy.stats.bartlett` 函数，请使用 `{func}`scipy.stats.bartlett``。
格式： MyST Markdown 支持标准的 Markdown 格式，例如粗体文本、斜体文本和代码块。例如，要使文本粗体，您可以使用双星号：`**bold text**`。要使文本成为等宽/代码格式，您可以使用*单*反引号：``code``。
图像： 如果您的笔记本包含静态图像，您可以使用以下语法将其包含在 MyST Markdown 文件中：`![alt text](path/to/image.png)`。图像通常存储在 MyST Markdown 文件所在的同一文件夹中，但您也可以使用相对路径引用其他文件夹中的图像。请注意，已执行单元格的输出不应包含在版本控制中，因为它们将在 SciPy 文档构建期间执行笔记本时自动生成。
链接到 MyST Markdown 页面： MyST Markdown 支持添加链接锚点，可用于从其他文档链接到特定页面或文档部分。要为页面添加锚点，请在要引用的文档的所需位置添加 `(anchor_name)=`。从其他 markdown 页面，您可以使用以下语法链接到此锚点：`{ref}`anchor_name``。从其他 reST 页面，您可以使用以下语法链接到此锚点：`:ref:`anchor_name``。

使笔记本具有交互性#

如果您希望在 SciPy 文档网站中渲染笔记本时启用交互性，您需要在 markdown 文件开头添加以下代码片段

```{eval-rst}
.. notebooklite:: <filename>.md
   :new_tab: True
```

其中 `<filename>.md` 应替换为您正在处理的文件名。这将创建一个按钮，允许用户在新标签页中打开笔记本并与之交互。请参阅 Bartlett 的方差相等性检验（及其源代码）作为示例。

注意

为了简单起见，我们不希望某些笔记本单元格在渲染的文档中可见。我们可以通过将 `"jupyterlite_sphinx_strip"` 添加到相应单元格元数据的标签部分来隐藏它们。要在 Markdown 文件中执行此操作，请在要隐藏的单元格前添加以下代码片段

+++ {"tags": ["jupyterlite_sphinx_strip"]}

请注意，`+++` 符号应成对出现，包围您要隐藏的单元格。

请访问 NotebookLite 指令文档以获取更多详细信息和选项。

在 Jupyter Notebook 应用程序中打开 MyST Markdown 文件#

如果您安装了 `jupytext` 工具，您可以在 Jupyter Notebook 应用程序中打开 MyST Markdown `.md` 文件并执行它们，就像处理 `.ipynb` 文件一样。

将 `.rst` 文件转换为 MyST Markdown#

要将 reStructuredText (`.rst`) 文件转换为 MyST Markdown (`.md`)，您可以遵循上述格式说明。您还可以使用 RST-to-MyST 等工具来自动化转换，但请注意，可能需要进行一些审查以确保转换正确。特别是，一些 reStructuredText 指令可能需要包装在 `{eval-rst}` MyST 指令中，如下所示

Some Markdown here

```{eval-rst}
.. some_rest_directive_here::
  :some_option: some_value
```

Some more Markdown here