为 Sphinx-Gallery 结构化 Python 脚本#

本页介绍了用于生成渲染的 HTML 画廊页面的 Python 脚本的结构和语法。

一个简单的示例#

Sphinx-Gallery 期望每个 Python 文件包含两部分：

一个文档字符串，用 reST 编写，定义示例的标题。它必须以定义 reST 标题开头。标题可以包含任何标点符号，但不能以重复超过 3 次的相同标点符号开头。例如：
```
"""
"This" is my example-script
===========================

This example doesn't do much, it just makes a simple plot
"""
```
Python 代码。这可以是您希望使用的任何有效的 Python 代码。生成的任何 Matplotlib 图像都会保存到磁盘，并且生成的 reST 将使用内置示例显示这些图像。默认情况下，只有由 Matplotlib 或基于 Matplotlib 的软件包（例如，Seaborn 或 Yellowbrick）生成的图像才会保存和显示。但是，您可以将其更改为包含其他软件包，请参阅图像抓取器。

在示例 Python 文件中嵌入 reST#

此外，您可以在 Python 脚本中嵌入 reST 语法。reST 允许您轻松添加格式化文本、数学方程式和引用链接，包括交叉引用其他示例。这将与 Python 代码及其输出一起内联渲染，类似于 Jupyter Notebook 的结构（实际上，Sphinx-Gallery 也创建了每个构建的示例的 Jupyter Notebook）。

您可以通过包含一行 >= 20 个 # 符号、#%% 或 # %% 来在示例 Python 中嵌入 reST。为了保持一致性，建议您在项目中只使用上述三种“块分隔符”选项之一。如果使用一行 #，建议使用 79 个 #，如下所示：

###############################################################################

任何注释行（以 # 后跟一个空格开头，以符合 PEP8 规范）紧接在块分隔符之后，将在生成的画廊示例中作为 reST 渲染。要切换回编写代码，请停止以 # 和空格开头，或者在编写代码注释之前留出一行空白。因此，您可以轻松地在文本和代码“块”之间交替。例如：

# This is commented python
myvariable = 2
print("my variable is {}".format(myvariable))

# %%
# This is a section header
# ------------------------
#
# In the built documentation, it will be rendered as reST. All reST lines
# must begin with '# ' (note the space) including underlines below section
# headers.

# These lines won't be rendered as reST because there is a gap after the last
# commented reST block. Instead, they'll resolve as regular Python comments.
# Normal Python code can follow these comments.
print('my variable plus 2 is {}'.format(myvariable + 2))

语法 #%% 和 # %% 与 Visual Studio Code Python 扩展、Visual Studio Python 工具、Jupytext、Pycharm 专业版、Hydrogen 插件（用于 Atom）和 Spyder 中的“代码块”（或“代码单元”）分隔符语法一致。请注意，虽然这些编辑器/IDE 的文档可能只提及 #%% 或 # %% 之一，但实际上两者都可以。使用这些编辑器/IDE，一行开头的 #%% 或 # %% 表示新代码块的开始。代码块允许您将代码分成块，就像在 Jupyter Notebook 中一样。一个代码块中的所有代码都可以轻松地一起执行。当编写 Sphinx-Gallery .py 示例时，此功能很有用，因为块允许您轻松创建后续 Sphinx-Gallery 文本和代码块对。

以下是用“代码块”功能的示例 Python 文件的内容

"""
This is my example script
=========================

This example doesn't do much, it just makes a simple plot
"""

# %%
# This is a section header
# ------------------------
# This is the first section!
# The `#%%` signifies to Sphinx-Gallery that this text should be rendered as
# reST and if using one of the above IDE/plugin's, also signifies the start of a
# 'code block'.

# This line won't be rendered as reST because there's a space after the last block.
myvariable = 2
print("my variable is {}".format(myvariable))
# This is the end of the 'code block' (if using an above IDE). All code within
# this block can be easily executed all at once.

# %%
# This is another section header
# ------------------------------
#
# In the built documentation, it will be rendered as reST after the code above!
# This is also another code block.

print('my variable plus 2 is {}'.format(myvariable + 2))

为了清楚起见，请参考渲染后的示例交替文本和代码，并将其与生成的 原始 python 脚本 进行比较

其他编程语言中的示例#

Sphinx-Gallery 还支持为用除 Python 之外的编程语言编写的示例渲染 HTML 页面，尽管这些示例目前没有执行或扫描输出。请参阅文件名/忽略模式以了解配置设置。

对于此类示例，示例的标题由文件中的第一个注释块定义，该块必须包含 reST 标题，并且可以包含应出现在第一个代码块之上的任何其他 reST 内容。例如，C++ 示例可以从以下代码开头：

// My Awesome Example
// ==================
//
// The description continues as long as there are lines
// that start with a comment character.

reST 内容同样可以嵌入在用特殊分隔符标记的注释中，其中该分隔符取决于示例语言使用的注释字符。有效的特殊分隔符为：

注释字符后跟 %%。例如，对于 C++，为 //%%。
注释字符后跟一个空格，再后跟 %%。例如，对于 C++，为 // %%。
至少包含 20 个注释字符的一行。例如，对于 C++，为 ////////////////////。

同一行上特殊分隔符后面的任何文本都将被转换为 reST 标题（用 - 下划线）。reST 块将一直持续到遇到不以注释字符开头的行为止。以下是一些示例：

// %% Important Heading
// This is some text in a reST block in C++, appearing underneath a heading.
//
// * Start a list
// * Check it twice

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! This is the start of a reST block in Fortran 90.
!
! It can contain multiple paragraphs.

对于使用 C 样式多行注释的语言，支持以下样式：

/* %%
 * Subheading
 * ----------
 *
 * Description
 */

int y = 3;

/**************************/
/* Another subheading     */
/* ------------------     */
/*                        */
/* Description            */
/**************************/
double z = 1.5;

最后，为了与 Matlab 使用简单的 %% 分隔符标记代码部分的做法兼容，除了上面描述的多语言语法之外，这在 Matlab 源文件中也是允许作为特殊分隔符的：

%% Heading
% some text below the heading

纯 reST 示例#

Sphinx-Gallery 从 Python 脚本生成示例，因此不支持用纯 reST 文件编写的示例。如果您希望为普通 reST 文档的代码块中的函数生成超链接（链接到其相应的在线文档），您可能会发现 sphinx-codeautolink 有用。