交叉引用

Sphinx 使用解释型文本角色将语义标记插入到文档中，格式为 :rolename:`content` ，交叉引用语法属于解释型文本角色的一种。

交叉引用类似于网页文件中的超链接，使文档的内容之间相互引用，这也是文档构建的基本功能。

注意

交叉引用前后必须有空格，用于区分文本和交叉引用。

交叉引用文件

:doc: 角色链接到指定的文件，文档名称使用相对路径方式指定。例如：:doc:`../people` ，引用时不包含文件扩展名。

交叉引用默认使用引用文件的标题名来显示，使用超链接的样式可以自定义交叉引用文本，比如 :doc:`title <../people>` 。

交叉引用任意位置

为了支持对文档中任意位置的交叉引用，必须配合标签使用。标签名在整个文档中必须是唯一的。

定义标签名类似于指令语法，但是标签名必须以 _ 开头，最后是一个冒号。

使用 :ref: 角色链接到标签位置，链接的标签名忽略标签开头的 _ 。

.. _my-reference-label:

Section to cross-reference
====================================

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

引用可下载文件

:download: 角色链接到源目录中可下载的文件。输出时会自动将可下载的文件放在输出目录的 _downloads 子目录中。

See :download:`this example script <../example.py>`.