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