Question

我可以使用Sphinx's domain-aware ObjectDescription为其创建精美的呈现文档。例如：

.. py:function:: pyfunc()

   Describes a Python function.

这以一种很好的方式呈现了内容，并且与模块索引，引用等一起使用时效果很好。太酷了！

现在，假设我在源文档src/mymodule/functions.rst中有该指令，并且在src/guide/getting-started.rst中有很多文本，我可以引用类似的对象

:py:func:`pyfunc`

也很酷！

现在，我的实际问题是；我还能告诉Sphinx编写者为该对象重新渲染相同的文档片段吗？为了使用户不必离开“入门”页面，我只想再次包含单个内容。

我尝试做的事情：

只需复制内容。这将导致警告，对象被多次定义，损害了索引，因此，如果运气不好，引用将不会指向项目中的“权威”位置。不好。
将每个对象记录在其自己的文件中，然后在要呈现该对象的每个文档中使用.. include:: rel/path/to/pyfunc.rst。由于这些包含的内容在ReST级别上是原义的，因此导致与上述选项相同的缺点。：-（

因此，我正在寻找一种解决方案，可以告诉Sphinx的渲染器/编写器仅重新渲染引用的内容，而不产生链接。不应将其添加到索引中以进行简单的重新渲染。

我可以使用自定义扩展名或特定于域的自定义解决方案-我已经在使用自己的自定义域，但是我只是将上面的通用Python域用作一个众所周知的示例。

^{用例的上下文：我正在构建一个Protobuf域。 Protobuf消息和枚举已被大量重用，我想在页面上内联显示常见重用对象的上下文，这对读者很有用。这意味着它会在整个项目中有目的地重复，而不是一直走开。但是，只有参考页面应该是“权威的”。}

Answer 1

我成功地做了一个肮脏的黑客：滥用XRef角色逻辑。 Sphinx中的交叉引用通过生成任意“节点”来动态呈现（例如Table 23）。通过：

...这基本上可以满足我的需求。但是，这真丑。

我在Protobuf Domain扩展名中实现的工作示例。