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 文本)。
文档的结构由标题样式的连续性决定，这意味着，通过对 “Usage” 章节使用 === 之后对 “Installation” 章节使用 ---，您已将 “Installation” 声明为 “Usage” 的子章节。
要完成此过程，请在 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 角色，并添加一个显式的标签，该标签充当 目标。
例如，要引用 “Installation” 子章节，请在标题前添加标签，如下所示
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 中文档化代码对象 呢？请继续阅读！