在使用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

在您的第一個文件中？