交叉引用

4.2. 交叉引用#

从形式上定义，交叉引用是指在某处通过名称定义要引用的内容， 在引用处通过名称引用定义的内容的方式。

前面说的图片、表格、数学表达式都涉及到局部使用的交叉引用。 当然交叉引用不限于这样的局部使用，其适应的场景应该是全局使用的方式。

这里进一步介绍交叉引用的一些情况。

4.2.1. 引用文档#

语法：

自定义引用文字

:doc:`引用本地的其它rst文档,rst后缀要省略，如about_us <../about_us>`

使用标题文字
:doc:`../about_us`

效果：

4.2.2. 使用标签引用文档#

要在被引用的文件头定义标签，如about_us.rst文件头写 “label_first” 的标签，具体请查看该文档的源码

语法：

:ref:`自定义链接文字 <label_first>`

:ref:`label_first`

若要跨文档引用标题，可以使用自动切片扩展插件，它的使用方式如下：

某个文档：

=============
Some Document
=============


Internal Headline
=================

然后在另一个文档引用：

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

此扩展程序是内置的，因此您只需编辑即可 conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

唯一需要注意的是，现在需要在整个文档集合中避免重复的标题。

4.2.3. 引用非rst文档#

会呈现出点击后下载文件的效果。注意这种引用方式在生成pdf文件时链接会无效。

语法：

:download:`引用非rst的本地文档 <./requirements.txt>`.

效果：

引用非rst的本地文档.

目录