在Sphinx中，我可以注册一堆应该始终转换为链接的关键字吗？

Question

我的文档字符串引用了我定义的其他python类。每次Sphinx遇到这些类之一时，我希望它为该其他类插入指向文档的链接。在狮身人面像中有可能吗？

具体来说，我有一个文档字符串，如：

'''This class contains a bunch of Foo objects'''

我可以写：

'''This class contains a bunch of :class:`~foo.Foo` objects'''

但是我更希望Sphinx查找所有匹配Foo的文本，并使其看起来好像我已经键入了：class：~foo.Foo

Answer 1

在我的项目中，我有一个头文件，其中包含所有“重要”类和全局函数及其缩写。两个示例行：

.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>`
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>`

在rst文件中，包括此头文件。然后，我可以在任何rst文件中使用宏：

.. include:: defs.hrst

|PostItem| is a nice class. |PostNotFoundError|, on the other hand is not.

（（您也可以使用autogen扩展名包含来自Python源文件的文档字符串。这些宏也将被替换。）

关于您的示例：我将Foo添加到头文件并以这种方式写入文档字符串：
'''This class contains a bunch of |Foo| objects'''

Answer 2

https://www.sphinx-doc.org/en/2.0/usage/restructuredtext/domains.html#cross-referencing-python-objects

我想进入Foo并让Sphinx解释它，就像我写了：class：~foo.Foo

听起来不切实际。似乎它会使RST尝试解析您的文本瘫痪。寻找解释文本和RST支持的一些引用规则（*_|`）与实际的限制有关。

您的要求可能导致RST花一整天时间在每个可能的上下文中检查每个实例Foo，并指出您是否想要链接。仅在Foo的其他情况下，您需要这样做；琐碎的搜索和替换将不起作用。

您可以将文档字符串预处理弄乱。

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#docstring-preprocessing

这可以让您尝试对文档字符串文本进行全局搜索和替换策略。