使用：ref：在Python文檔中使用Sphinx

我正在使用Sphinx來記錄一個python項目，並且我正在嘗試創建一個可重用的提示以用於多個位置。使用：ref：在Python文檔中使用Sphinx

通常情況下，我會用下面的語法在Python文件：

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

現在這工作我是否把它放在文件的開頭，對下類定義或向右在函數定義下。

我發現Sphinx's manual爲：參考：，這表明使用標籤：

.. _my_reusable_tip: 

.. tip:: 
    ...

然後調用這個技巧與:ref:`my_reusable_tip`任何地方我想要的。該手冊指出'它可以跨文件工作，當章節標題改變時，以及支持所有交叉引用的構建器'

問題是，寫入的項目中的.py文件沒有關係標籤和提示定義，:ref:`my_reusable_tip`只顯示'my_reusable_tip'，而不是提示本身。

什麼我使用構建文檔

sphinx-apidoc -f -F -o 
make html

我敢肯定我的邏輯是在某些方面有缺陷，但我想不出爲什麼。我知道獅身人面像在項目中搜索reStructuredText，如果可以的話就渲染它，但我想我在這裏錯過了一些東西。

我試圖將此標籤添加到「」「中的單獨.py文件中，並在不帶有」「的單獨.txt文件中。
我試着用標籤定義創建一個.rst文件並重建html文檔。

我在這裏錯過了什麼？

Python 3.4.3順便說一句。

來源

2015-12-03 Derorrist

剛開始使用新結構化指令

.. include:: ./my_reusable_tip.txt

在您的第一個文件

？

來源

2015-12-06 08:35:46 aflp91

這實際上是有效的....！謝謝！有沒有辦法創建一個「全球」包括？那麼所有其他的.srt文件將從它繼承？或者可能是conf.py中的一個值，它會將行添加到所有.srt文件中？我試圖將.txt文件複製到_templates，這沒有奏效。沒有將include行添加到index.srt – Derorrist

在獅身人面像中，:ref:只是鏈接（或引用）文檔另一部分的更健壯的方式。因此，您使用:ref:只會提供指向標籤的超鏈接。

這不是用代替或擴大塊的方法。

Inline substitutions可通過使用|...|獲得，但是，內聯替換不能用於替代塊，因爲您似乎需要。

RestructuredText不是模板語言，因此不提供類似宏的設施。如果您需要它，另一種解決方案是使用模板庫（例如mako或jinja）來處理這類問題。

來源

2015-12-03 08:39:43 donkopotamus

嗯，這是不幸的，但可以理解。我覺得忍者就是要走的路。感謝您花時間回答 – Derorrist

使用：ref：在Python文檔中使用Sphinx

回答

相關問題