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 中记录代码对象怎么样？继续阅读！