主题特定元素#

有一些元素是该主题独特或特别重要的。其中一些是通过该主题独有的配置或 Markdown 语法触发的，将在下面详细介绍它们。

数学#

大多数 Sphinx 网站都支持数学公式，但对于科学计算来说尤为重要，因此在这里也展示了对其的支持。

这是行内公式：\(X_{0:5} = (X_0, X_1, X_2, X_3, X_4)\) 和 \(another\) 以及 \(x^2 x^3 x^4\) 另一个。这是测试垂直高度的公式：\(\frac{\partial^2 f}{\partial \phi^2}\)。这是块级公式：

(1)#\[\nabla^2 f = \frac{1}{r^2} \frac{\partial}{\partial r} \left( r^2 \frac{\partial f}{\partial r} \right) + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}\]

这是带有标签的非常长的公式！

(2)#\[\nabla^2 f = \frac{1}{r^2} \frac{\partial}{\partial r} \left( r^2 \frac{\partial f}{\partial r} \right) + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2} \nabla^2 f = \frac{1}{r^2} \frac{\partial}{\partial r} \left( r^2 \frac{\partial f}{\partial r} \right) + \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta} \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) + \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}\]

您可以像上面的公式 (1) 和 (2) 一样为公式添加链接。

代码块#

代码块的样式灵感来自 GitHub 的代码块样式，并且还支持代码块标题/说明。更多信息请参阅 Sphinx 关于代码块的文档。

print("A regular code block")
print("A regular code block")
print("A regular code block")

您还可以为代码块提供标题，标题将显示在代码的正上方。例如，以下代码：

.. code-block:: python
    :caption: python.py

    print("A code block with a caption.")

```{code-block} python
:caption: python.py

print("A code block with a caption.")
```

结果是：

python.py#
print("A code block with a caption.")

您还可以显示行号。例如，以下代码：

..  code-block:: python
    :caption: python.py
    :linenos:

    print("A code block with a caption and line numbers.")
    print("A code block with a caption and line numbers.")
    print("A code block with a caption and line numbers.")

```{code-block} python
:caption: python.py
:linenos:

print("A code block with a caption and line numbers.")
print("A code block with a caption and line numbers.")
print("A code block with a caption and line numbers.")
```

结果是：

python.py#
1print("A code block with a caption and line numbers.")
2print("A code block with a caption and line numbers.")
3print("A code block with a caption and line numbers.")

内联代码#

直接使用时，code 角色仅显示文本，而不进行语法高亮，作为字面量。如 Sphinx 文档 中所述，您还可以通过定义自定义角色来启用语法高亮。然后它将使用与 code-block 指令相同的高亮器。

.. role:: python(code)
   :language: python

In Python you can :python:`import sphinx`.

```{role} python(code)
:language: python
```

In Python you can {python}`import sphinx`.

在 Python 中，您可以 import sphinx。

代码执行#

该主题支持 Jupyter 执行库，因此您可以在每次构建时以编程方式更新您的文档。有关示例，请参阅 PyData Library Styles。

警告侧边栏#

A sidebar admonition!

I was made with the {admonition} directive and a sidebar class.

该主题支持一种简写方式，使 警告框表现得像侧边栏。这可以成为一种突出显示内容的有用方式，而不会过多地中断垂直流。

例如，右侧是“警告侧边栏”和传统的 Sphinx 侧边栏。

要使警告框表现得像侧边栏，请将 sidebar 类添加到其类列表中。本节中的警告侧边栏是使用以下 Markdown 创建的：

.. admonition:: A sidebar admonition!
    :class: sidebar note

    Some sidebar content.

```{admonition} A sidebar admonition!
:class: sidebar note
Some sidebar content.
```

脚注#

这是数字脚注[1]，另一个（前面有空格）[2]，命名脚注[3]，以及符号脚注[4]。在渲染的 HTML 中，它们最终都会显示为数字，但在源代码中它们看起来像 [^1]、[^2]、[^named] 和 [^*]。