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

回答

相关问题