Sphinx 中的叙事文档

在多个页面上构建你的文档结构

由 sphinx-quickstart 创建的 index.rst 文件是 根文件，其主要功能是作为欢迎页和包含 “目录树”（或 toctree）的根。Sphinx 允许你从不同的文件中组装项目，这在项目增长时很有帮助。

作为一个例子，创建新的文件 docs/source/usage.rst （在 index.rst 旁边），内容如下：

docs/source/usage.rst
Usage
=====

Installation
------------

To use Lumache, first install it using pip:

.. code-block:: console

   (.venv) $ pip install lumache

这个新文件包含两个 章节 标题，正常的段落文本，以及 code-block 指令，该指令将内容块渲染成源代码，并有适当的语法高亮显示（在本例中是通用的 console 文本）。

文件的结构是由连续的标题决定的样式，这意味着在 “Installation” 部分使用 ---，而在 “Usage” 部分使用 ===，就意味着你已经声明了 “Installation” 是 “Usage” 的小节。

为了完成这个过程，在 index.rst 的末尾添加 toctree 指令，包括你刚刚创建的文件，如下所示：

docs/source/index.rst
Contents
--------

.. toctree::

   usage

这一步将该文件插入 toctree 的根部，所以现在它属于你的项目结构，到目前为止，它看起来像这样：

index
└── usage

如果你运行 make html 构建 HTML 文档，你会看到 toctree 被渲染成一个超链接的列表，这允许你导航到你刚刚创建的新页面。很好！

警告

在 toctree 之外的文档将导致在构建过程中出现 WARNING: 文档没有加入到任何目录树中 的信息，并且对用户来说将无法访问。

添加交叉引用

Sphinx 的一个强大的功能是能够无缝添加 交叉引用 到文档的特定部分：一个文档，一个章节，一个图，一个代码对象，等等。这个教程中充满了这些内容！

要增加一个交叉引用，请在 index.rst 中的介绍段之后写下这句话：

docs/source/index.rst
Check out the :doc:`usage` section for further information.

你使用的 doc 角色 自动引用项目中的一个特定文件，在这种情况下，你先前创建的 usage.rst。

另外，你也可以向项目的任意部分添加一个交叉引用。为此，你需要使用 ref 角色，并添加一个明确的 标签，作为 目标。

例如，为了引用 “Installation” 小节，在标题前添加一个标签，如下所示：

docs/source/usage.rst
Usage
=====

.. _installation:

Installation
------------

...

并使你在 index.rst 中添加的句子看起来像这样：

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