在Sphinx中,我可以注册一堆应该始终被翻译成链接的关键字吗？

Question

我的doc字符串引用了我定义的其他python类.每当Sphinx遇到其中一个类时,我希望它为该另一个类的文档插入一个链接.狮身人面像有可能吗？

具体来说,我有一个doc字符串,如:

'''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到头文件并以这种方式编写docstring:

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