如何使用 sphinx 从模块的文档字符串中引用 *.rst 文件

Question

我写了一个 rst 格式的小教程。现在对于 apidoc 生成的文档，我想在文档字符串中引用该教程使用：

:any:`<my_tut>`

其中 my_tut.rst 位于我的 Sphinx 文档源文件夹的顶级目录中。但是，我收到错误

WARNING: 'any' reference target not found: my_tut

添加信息：

apidoc 的输出不在顶层源文件夹中，而是在名为 code 的子文件夹中。

Answer 1

:doc:角色可用于创建cross-reference到my_tut.rst:

:doc:`my_tut`

如果 link 源和 link 目标位于不同的文件夹中，则需要考虑这一点。目标比源高一级，它看起来像这样：

:doc:`../my_tut`

---

另一种方法是在 my_tut.rst 中的相关标题之前添加一个 label，并将其用作 cross-reference 目标。如果标签定义是 .. _my_label:，您可以这样引用它：

:any:`my_label`

您也可以使用 :ref:`my_label`。