块

块引用

块引用由缩进的正文元素组成

我的理论，作者 A. Elk。括号错，括号。这个理论如下，现在开始。所有雷龙的一端都很细，中间非常粗，然后远端又细。这就是我的理论，是我的，属于我，我拥有它，它也是我的。

—安妮·埃尔克（小姐）

题词

https://docutils.sourceforge.io/docs/ref/rst/directives.html#epigraph

我的理论，作者 A. Elk。括号错，括号。这个理论如下，现在开始。所有雷龙的一端都很细，中间非常粗，然后远端又细。这就是我的理论，是我的，属于我，我拥有它，它也是我的。

—安妮·埃尔克（小姐）

摘录

https://docutils.sourceforge.io/docs/ref/rst/directives.html#pull-quote

我的理论，作者 A. Elk。括号错，括号。这个理论如下，现在开始。所有雷龙的一端都很细，中间非常粗，然后远端又细。这就是我的理论，是我的，属于我，我拥有它，它也是我的。

—安妮·埃尔克（小姐）

重点

https://docutils.sourceforge.io/docs/ref/rst/directives.html#highlights

我的理论，作者 A. Elk。括号错，括号。这个理论如下，现在开始。所有雷龙的一端都很细，中间非常粗，然后远端又细。这就是我的理论，是我的，属于我，我拥有它，它也是我的。

—安妮·埃尔克（小姐）

行块

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks

这是一个普通文本段落。

这是一个行块。它以空行结束。

每行新行都以垂直线（“|”）开头。

保留换行符和初始缩进。

续行是长行的包装部分；它们以空格代替垂直线。

续行的左边缘不必与上面文本的左边缘对齐。

这是一个第二个行块。

允许内部有空行，但它们必须以“|”开头。

这是一个普通的文本段落。

等宽块

Sphinx 支持多种等宽块。本节旨在展示所有作者在编写本文档时已知的所有等宽块。

生产列表

https://sphinx-doc.cn/en/master/usage/restructuredtext/directives.html#directive-productionlist

此指令用于包含一组生产。每个生产都在一行上给出，包括一个名称，用冒号与后面的定义分隔。

这只是显示为一个普通的 <pre>，这……既好又有点烦人。

try_stmt  ::=  try1_stmt | try2_stmt
try1_stmt ::=  "try" ":" suite
               ("except" [expression ["," target]] ":" suite)+
               ["else" ":" suite]
               ["finally" ":" suite]
try2_stmt ::=  "try" ":" suite
               "finally" ":" suite
               "this-is-intentionally-very-stupidly-long-to-make-sure-that-this-has-a-proper-scrollbar"

文字块

https://sphinx-doc.cn/en/master/usage/restructuredtext/basics.html#literal-blocks

包含一段文本，其中换行符和空格很重要，必须保留。

这是一个普通的文本段落。下一个段落是一个代码示例。

It is not processed in any way, except
that the indentation is removed.

It can span multiple lines.

这是一个普通的文本段落。

它们可以不缩进地引用

>> Great idea!
>
> Why didn't I think of that?

文字包含也可以有标题。

from requests.exceptions import ConnectionError, HTTPError, RetryError
from sphinx.application import Sphinx
from sphinx.builders.dirhtml import DirectoryHTMLBuilder
from sphinx.errors import ExtensionError

from . import edit_this_page, logo, pygments, short_link, toctree, translator, utils

__version__ = "0.16.0"


def update_config(app):

Doctest 块

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#doctest-blocks

Doctest 块是交互式 Python 会话，剪切粘贴到文档字符串中。它们旨在通过示例说明用法，并通过 Python 标准库中的 doctest 模块提供一个优雅且强大的测试环境。

注意

这很好。

>>> print('Python-specific usage examples; begun with ">>>"')
Python-specific usage examples; begun with ">>>"
>>> print("(cut and pasted from interactive Python sessions)")
(cut and pasted from interactive Python sessions)
>>> print("This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly.")
This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly.

解析文字

https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal-block

它等效于使用不同渲染的行块：通常使用打字机/等宽字体，就像普通文字块一样。解析文字块对于向代码示例添加超链接很有用。

# parsed-literal test
curl -O http://someurl/release-0.1.0.tar-gz
echo "This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly."

代码块

https://docutils.sourceforge.io/docs/ref/rst/directives.html#code

“code”指令构建一个文字块 [包含代码]。

它有一个别名 code-block。

from typing import Iterator

# This is an example
class Math:
    @staticmethod
    def fib(n: int) -> Iterator[int]:
        """Fibonacci series up to n"""
        a, b = 0, 1
        while a < n:
            yield a
            a, b = b, a + b


result = sum(Math.fib(42))
print("The answer is {}".format(result))

带标题

代码块可以有标题，这也会添加一个链接到它。

{
  "session_name": "shorthands",
  "windows": [
    {
      "panes": [
        {
          "shell_command": "echo 'This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly.'"
        }
      ],
      "window_name": "long form"
    }
  ]
}

带行号

def some_function():
    interesting = False
    print("This line is highlighted.")
    print("This one is not...")
    print("...but this one is.")
    print(
        "This is an intentionally very long line because I want to make sure that we are handling scrollable code blocks correctly."
    )

不突出显示

# Taken from https://en.wikipedia.org/wiki/Pseudocode#Example
algorithm ford-fulkerson is
    input: Graph G with flow capacity c,
        source node s,
        sink node t
    output: Flow f such that f is maximal from s to t

    (Note that f(u,v) is the flow from node u to node v, and c(u,v) is the flow capacity from node u to node v)

    for each edge (u, v) in GE do
        f(u, v) ← 0
        f(v, u) ← 0

    while there exists a path p from s to t in the residual network Gf do
        let cf be the flow capacity of the residual network Gf
        cf(p) ← min{cf(u, v) | (u, v) in p}
        for each edge (u, v) in p do
            f(u, v) ←  f(u, v) + cf(p)
            f(v, u) ← −f(u, v)

    return f