如何使用 Sphinx 文档重新渲染某些对象描述？

Question

使用Sphinx's domain-awareObjectDescriptions 我可以为它们创建精美的渲染文档。例如：

.. py:function:: pyfunc()

   Describes a Python function.

这以一种很好的方式呈现内容，并且与模块索引、引用等一起工作得非常好。到目前为止很酷！

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

:py:func:`pyfunc`

也很酷！

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

我尝试做的事情：

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

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

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

---

用例的上下文：我正在构建一个 Protobuf 域。 Protobuf 消息和枚举被重用了很多，我想在对读者有用的页面上展示常用重用对象的上下文。这意味着它会在整个项目中重复使用，目的是在它被认为有用的地方而不是一直走开。然而，只有参考页面应该是“权威的”。

Answer 1

我在一个肮脏的 hack 上取得了成功：滥用外部参照角色逻辑。 Sphinx 中的交叉引用通过生成任意“节点”动态呈现（例如Table 23）。作者：

• 在自定义域中解析期间保留父节点的副本
• 注册自定义 Sphinx/ReST XRef 角色以渲染一整组节点（保存的父节点）
• 再次重新运行 ReferencesResolver

...这基本上可以满足我的需求。但是，糟糕，它相当丑陋。

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