Question

我正在使用Sphinx来记录python项目，并且我正在尝试创建一个可重复使用的提示，以便在多个位置使用。

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

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

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

我发现Sphinx's manual代表：ref：，建议使用标签：

.. _my_reusable_tip:

.. tip::
   ...

然后在我想要的任何地方使用:ref:`my_reusable_tip`拨打此提示。该手册指出，它可以跨文件，更改章节标题，以及支持交叉引用的所有构建器＆＃39;

问题是，在我编写标签和提示定义的项目中的哪个.py文件中，:ref:`my_reusable_tip`只显示＆＃39; my_reusable_tip＆＃39;而不是提示自己。

我用来构建文档的是

sphinx-apidoc -f -F -o
make html

我很确定我的逻辑在某些方面存在缺陷，但我无法弄清楚原因。我知道Sphinx在项目中搜索reStructuredText并在可能的情况下呈现它，但我想我在这里遗漏了一些东西。

我尝试将此标签添加到＆＃34;＆＃34;＆＃34;中所附的单独.py文件中，并添加到单独的.txt文件中，不附带＆＃34;＆＃34;＆＃34 ;
我尝试使用标签定义创建.rst文件并重建html文档。

我在这里缺少什么？

Python 3.4.3 BTW。

Answer 1

在sphinx中，Switch sw = new Switch(MainActivity.this); sw.setTextOn("start"); sw.setTextOff("close"); LinearLayout linearLayout = new LinearLayout(MainActivity.this); linearLayout.setLayoutParams(new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT,ViewGroup.LayoutParams.MATCH_PARENT)); linearLayout.setGravity(Gravity.CENTER_HORIZONTAL); linearLayout.addView(sw); AlertDialog.Builder myDialog = new AlertDialog.Builder(MainActivity.this); myDialog.setTitle("title"); myDialog.setMessage("message"); myDialog.setView(linearLayout); myDialog.show();只是一种更强大的链接（或引用）文档另一部分的方式。因此，使用:ref:只会提供标签的超链接。

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

使用:ref:可以使用

Inline substitutions，但是内联替换不能用于替换您似乎需要的块。

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

Answer 2

只需使用reStructuredText指令

.. include:: ./my_reusable_tip.txt

在你的第一个文件中？

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

2 个答案: