以 Jupyter Notebook 形式添加或编辑教程#

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

如果您有一个以 Jupyter Notebook 格式编写的文档（一个 .ipynb 文件），并且想将其作为 SciPy 文档的一部分提交，则有两种选择：您可以将其转换为 MyST Markdown 文件，并且只处理 .md 文件，或者您可以将您的 .ipynb 文件与 .md 文件配对并同时处理两者。请注意，.ipynb 文件不应提交给 SciPy 文档。

在本文档中，我们将介绍转换为 MyST Markdown 文件。有关 MyST-NB、Jupytext 和配对 Notebook 的更多信息，您还可以参考 NumPy Tutorials 上的配对教程。有关更多信息，请查阅 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
---

您无需编辑此预处理代码，因为它会自动生成。

链接、格式和图像#

将 Notebook 转换为 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 格式，例如粗体文本、斜体文本和代码块。例如，要使文本加粗，您可以使用双星号：**粗体文本**。要使文本等宽/格式化为代码，您可以使用单个反引号：`代码`。
图像： 如果您的 Notebook 包含静态图像，您可以使用以下语法将其包含在 MyST Markdown 文件中：![alt text](path/to/image.png)。图像通常存储在与 MyST Markdown 文件相同的文件夹中，但您也可以使用相对路径来引用其他文件夹中的图像。请注意，执行单元格的输出不应包含在版本控制中，因为在 SciPy 文档构建期间执行 Notebook 时，它们将自动生成。
链接到 MyST Markdown 页面： MyST Markdown 支持添加链接锚点，可用于从其他文档链接到特定页面或文档部分。要在页面中添加锚点，请将 (anchor_name)= 添加到要引用的文档中的所需位置。从其他 Markdown 页面，您可以使用以下语法链接到此锚点：{ref}`anchor_name`。从其他 reST 页面，您可以使用以下语法链接到此锚点：:ref:`anchor_name`。

使 Notebook 具有交互性#

如果您想在 SciPy 文档网站中呈现 Notebook 时启用其交互性，则需要在 Markdown 文件的开头添加以下代码段

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

其中 <filename>.md 应该替换为您正在处理的文件名。这将创建一个按钮，允许用户在新选项卡中打开 Notebook 并与之交互。有关示例，请参见 Bartlett 方差齐性检验（以及其来源）。

注意

为简单起见，我们不希望某些 Notebook 单元格在呈现的文档中可见。我们可以通过将 "jupyterlite_sphinx_strip" 添加到相应单元格元数据的标签部分来隐藏它们。为此，请在您要隐藏的单元格之前添加以下代码段

+++ {"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