在Python docstrings中使用：ref:使用Sphinx

Question

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

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

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

现在不管我把它放在文件的开头，在类定义下，还是在函数定义下，这都是有效的。在

我找到了Sphinx's manualfor:ref:，它建议使用一个标签：

^{pr2}$

然后在任何我想要的地方用:ref:`my_reusable_tip`调用这个技巧。 该手册指出“当节标题被更改时，它可以跨文件工作，并且适用于所有支持交叉引用的生成器”

问题是，我在项目中的哪个.py文件中编写了标签和提示定义，:ref:`my_reusable_tip`只显示“我的可重用提示”，而不是提示本身。在

我用来构建文档的是

sphinx-apidoc -f -F -o
make html

我很确定我的逻辑在某些方面是有缺陷的，但我不知道为什么。 我知道Sphinx在项目中搜索reStructuredText，并尽可能呈现它，但我想我在这里遗漏了一些东西。在

• 我试图将此标签添加到一个单独的.py文件中，并将其添加到一个单独的.txt文件中，而不包含“”。在
• 我尝试用标签定义创建一个.rst文件并重建html文档。在

我错过了什么？在

Python 3.4.3 BTW

Answer 1

只使用recostructedText指令

.. include:: ./my_reusable_tip.txt

在你的rst文件里？在

Answer 2

在sphinx中，:ref:只是链接（或引用）文档另一部分的更可靠的方法。因此，使用:ref:将只提供一个指向标签的超链接。在

它不是一种替代或扩展块的方法。在

使用|...|可以使用Inline substitutions，但是不能按照您的要求使用内联替换来替换块。在

RestructedText不是模板语言，因此不提供类似宏的工具。如果您需要它，另一种解决方案是使用模板库，例如mako或{}来处理此类问题。在