Sphinx 中的叙事文档¶
跨多个页面构建文档结构¶
由 sphinx-quickstart 创建的文件 index.rst 是 根文档，其主要功能是充当欢迎页面并包含“目录树”（或toctree）的根。Sphinx 允许你从不同的文件组装一个项目，这在项目规模增大时非常有用。
例如，创建一个新文件 docs/source/usage.rst（位于 index.rst 旁边），内容如下
Usage
=====
Installation
------------
To use Lumache, first install it using pip:
.. code-block:: console
(.venv) $ pip install lumache
此新文件包含两个 节 标题、普通段落文本和一个 code-block 指令，该指令将一段内容呈现为源代码，并进行适当的语法高亮显示（在本例中为通用的 console 文本）。
文档的结构由标题样式的顺序决定，这意味着，通过在“用法”部分的 === 之后使用 --- 作为“安装”部分，你已声明“安装”是“用法”的子节。
要完成此过程，请在 index.rst 的末尾添加一个 toctree 指令，其中包含你刚刚创建的文档，如下所示
Contents
--------
.. toctree::
usage
此步骤将该文档插入toctree的根目录，因此它现在属于你的项目结构的一部分，到目前为止，它看起来像这样
index
└── usage
如果你运行 make html 构建 HTML 文档，你会看到 toctree 被渲染为超链接列表，这使你能够导航到刚刚创建的新页面。很不错！
警告
toctree之外的文档会导致在构建过程中出现 WARNING: document isn't included in any toctree 消息，并且用户无法访问这些文档。
添加交叉引用¶
Sphinx 的一项强大功能是能够无缝地添加对文档特定部分的 交叉引用：文档、节、图形、代码对象等。本教程中到处都有这些！
要添加交叉引用，请在 index.rst 中的介绍段落之后立即编写以下句子
Check out the :doc:`usage` section for further information.
你使用的 doc 角色 自动引用项目中的特定文档，在本例中是之前创建的 usage.rst。
或者，你还可以添加对项目任意部分的交叉引用。为此，你需要使用 ref 角色，并添加一个作为 目标 的显式标签。
例如，要引用“安装”子节，请在标题之前添加一个标签，如下所示
Usage
=====
.. _installation:
Installation
------------
...
并将你在 index.rst 中添加的句子修改如下
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
这里有一个技巧：install 部分指定链接的外观（我们希望它是一个特定的词，以便句子有意义），而 <installation> 部分指的是我们要添加交叉引用的实际标签。如果你不包含显式标题，因此使用 :ref:`installation`，则将使用节标题（在本例中为 Installation）。:doc: 和 :ref: 角色都将在 HTML 文档中渲染为超链接。
那么 在 Sphinx 中记录代码对象 呢？继续阅读！