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 角色,并添加一个显式的 标签 作为 目标.
例如,要引用”安装”小节,请在标题前添加一个标签,如下所示:
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 中记录代码对象?继续阅读!