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

Question

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

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

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

现在无论我将其放在文件开头，在类定义下还是在函数定义下都可以使用。

我发现了Sphinx的 ：ref： 手册 ，该手册建议使用标签：

.. _my_reusable_tip:

.. tip::
   ...

然后在我想要的任何地方使用:ref:`my_reusable_tip`调用此技巧。 手册指出：“更改节标题后，以及对于所有支持交叉引用的构建器，它都可跨文件运行”

问题是，我在项目中的哪个.py文件中编写标签和提示定义都没有关系， :ref:`my_reusable_tip`仅显示'my_reusable_tip'，而不显示提示本身。

我用来构建文档的是

sphinx-apidoc -f -F -o
make html

我很确定我的逻辑在某些方面存在缺陷，但是我不知道为什么。 我知道Sphinx在项目中搜索reStructuredText并在可能的情况下对其进行渲染，但是我想我在这里丢失了一些东西。

• 我试图将此标签添加到用“”“括起来的单独的.py文件中，并添加到不包含”“”的单独.txt文件中。
• 我尝试使用标签定义创建.rst文件，然后重建html文档。

我在这里想念什么？

Python 3.4.3 BTW。

Answer 1

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

这不是替代或扩展块的方法。

可以使用|...|进行内联替换 |...| ，但是内联替换无法按照您的要求使用来替换块。

RestructuredText不是模板语言，因此不提供类似宏的功能。 如果您需要它，另一种解决方案是使用模板库（例如mako或jinja来处理此类问题。

Answer 2

仅使用reStructuredText指令

.. include:: ./my_reusable_tip.txt

在您的第一个文件中？