入门示例 - 绘制正弦函数#

这是一个演示 Matplotlib 绘图输出、嵌入式 reST、数学符号使用和与其他示例交叉链接的通用示例。将 source Python file 与下面的输出进行比较将很有帮助。

画廊示例的源文件应该以三引号的标题文档字符串开头。文档字符串之前的任何内容都会被 Sphinx-Gallery 忽略，不会出现在渲染的输出中，也不会被执行。此文档字符串需要一个 reST 标题，该标题用作示例的标题，并用于正确构建交叉引用链接。

代码和嵌入式 reST 文本块位于文档字符串之后。紧随文档字符串之后的第一个块默认被视为代码块，除非您使用 # 或 #%% 的一行指定它为文本块（见下文）。所有代码块都由 Sphinx-Gallery 执行，并且会捕获所有输出，包括绘图。通常，代码和文本块会交织在一起，以提供对代码正在做什么的叙述性解释或对代码输出的解释。

数学表达式可以包含为 LaTeX，并将使用 MathJax 渲染。要包含显示的数学符号，请使用指令 .. math::。要包含内联数学符号，请使用 :math: 角色。例如，我们即将绘制以下函数

\[x \rightarrow \sin(x)\]

这里，函数 \(\sin\) 在变量 \(x\) 定义的每个点处求值。在 Python 字符串中包含 LaTeX 时，请确保转义反斜杠或使用 raw docstring。在文本块中不需要这样做（见下文）。

# Code source: Óscar Nájera
# License: BSD 3 clause

import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 2 * np.pi, 100)
y = np.sin(x)

plt.plot(x, y)
plt.xlabel(r"$x$")
plt.ylabel(r"$\sin(x)$")
# To avoid matplotlib text output
plt.show()

要包含嵌入式 reST，请在您的 reST 和代码之间使用一行 >= 20 个 # 或 #%%（见在您的示例 Python 文件中嵌入 reST）。这会将您的示例分成不同的文本和代码块。您可以在嵌入的 reST 文本块下方继续编写代码

print("This example shows a sin plot!")

This example shows a sin plot!

文本块中的 LaTeX 语法不需要转义反斜杠

\[\sin\]

交叉引用#

您可以从文档的任何部分（包括其他示例）引用示例。 Sphinx-Gallery 会自动为每个示例创建引用标签。该标签由 .py 文件名组成，以 sphx_glr_ 为前缀，以及示例所在的文件夹名称。在下面，我们要交叉引用的示例位于 auto_examples（gallery_dirs；见配置和使用 Sphinx-Gallery）中，然后是子目录 no_output（因为该示例位于子画廊中）。示例的文件名为 plot_syntaxerror.py。因此，我们可以使用以下代码交叉链接到示例“语法错误”：:ref:`sphx_glr_auto_examples_no_output_plot_syntaxerror.py`。