在使用Sphinx的Python文档字符串中使用：ref:

我正在使用Sphinx来记录一个python项目，并试图创建一个可重用的技巧，用于多个位置

通常，我将在python文件中使用以下语法：

"""
.. tip::
    I want this tip to be used in several locations. Why?
        - Save time
        - Work less
"""

现在，无论我把它放在文件的开头，在类定义下，还是在函数定义下，它都可以工作

我发现for:ref:，建议使用标签：

.. _my_reusable_tip:

.. tip::
   ...

然后用

：ref:`my\u reusables\u tip`

调用此提示，只要我愿意。 该手册指出，“当节标题更改时，它可以跨文件工作，并且适用于所有支持交叉引用的构建器”

问题是，我在项目中的哪个.py文件中编写标签和提示定义并不重要，

：ref:'my\u reusables\u tip`

只显示'my\u reusables\u tip'，而不是提示本身

我用来构建文档的是

sphinx-apidoc -f -F -o
make html

我很确定我的逻辑在某种程度上是有缺陷的，但我不知道为什么。 我知道Sphinx会在项目中搜索重构文本，如果可以的话会进行渲染，但我想我在这里遗漏了一些东西

• 我试图将此标签添加到一个单独的.py文件中，该文件用“”括起来，并添加到一个单独的.txt文件中，但没有用“”括起来
• 我尝试使用标签定义创建一个.rst文件，并重建html文档

我错过了什么

---

Python3.4.3顺便说一句。

在sphinx中，a

：ref:

只是链接（或引用）文档另一部分的一种更健壮的方式。因此，您对

：ref:

的使用将提供指向标签的超链接

这不是替换或扩展块的方式

可以使用

|…|

，但是不能按照您的要求使用内联替换来替换块

---

StructuredText不是模板语言，因此不提供类似宏的功能。如果您需要它，另一种解决方案是使用模板库，如

mako

或

jinja

来处理此类问题。

仅使用StructuredText指令

.. include:: ./my_reusable_tip.txt

---

在您的rst文件中？

嗯，这很不幸，但可以理解。我认为金贾是一条路要走。感谢您抽出时间回答这个问题，它确实有效。。。。！谢谢有没有办法创建“全局”包含？那么所有其他.srt文件都将从中继承？或者可能是conf.py中的一个值，该值会将该行添加到所有.srt文件中？我尝试将.txt文件复制到_模板，但没有成功。也没有将include行添加到index.srt