Sphinx的叙事性文档¶
跨多页组织您的文档¶
档案 index.rst vt.由.创造 sphinx-quickstart 是 root document ，其主要功能是充当欢迎页面并包含“目录树”的根(或 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
这个新文件包含两个 section 页眉、普通段落文本和 code-block 指令，该指令将内容块呈现为源代码，并使用适当的语法突出显示(在本例中为泛型 console 文本)。
文档的结构由一系列标题样式决定，这意味着通过使用 --- 之后的“安装”部分 === 对于“Usage”部分，您已经将“Installation”声明为 subsection “用法”的概念。
要完成该过程，请添加一个 toctree directive 在…的末尾 index.rst 包括您刚刚创建的文档，如下所示：
Contents
--------
.. toctree::
usage
此步骤将该文档插入到 toctree ，所以现在它属于您的项目的结构，到目前为止看起来是这样的：
index
└── usage
如果您构建的HTML文档运行 make html ，您将看到 toctree 以超链接列表的形式呈现，这使您可以导航到刚刚创建的新页。干净利落！
警告
外部文档 toctree 将导致 WARNING: document isn't included in any toctree 消息，并且用户将无法访问。
添加交叉引用¶
Sphinx的一个强大功能是能够无缝地添加 cross-references 文档的特定部分：文档、章节、图形、代码对象等。本教程中充满了这些内容！
要添加交叉引用，请将这句话写在#中的引言段落之后 index.rst ：
Check out the :doc:`usage` section for further information.
这个 doc role 您使用的会自动引用项目中的特定文档，在本例中为 usage.rst 你之前创造的。
或者，您也可以添加对项目任意部分的交叉引用。为此，您需要使用 ref 角色，并添加显式 label 它的作用就是 a target 。
例如，要引用“安装”小节，请在标题前添加一个标签，如下所示：
Usage
=====
.. _installation:
Installation
------------
...
并将您添加的句子 index.rst 如下所示：
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
请注意这里的一个技巧： install 部分指定链接的外观(我们希望它是一个特定的单词，这样句子就有意义了)，而 <installation> Part指的是我们要添加交叉引用的实际标签。如果不包括显式标题，则使用 :ref:`installation ，将使用部分标题(在本例中， ``Installation` )。这两个 :doc: 以及 :ref: 角色将在HTML文档中呈现为超链接。
关于 documenting code objects in Sphinx ？继续读下去！