Sphinx文档中如何实现类链接加后缀无空格的正确渲染？

问题场景 #

编写Sphinx文档时，文档包含Foo和Bar类，想要写出如下内容：

A :class:`~.Foo` contains multiple :class:`~.Bar`s.

期望渲染后效果为：

A [Foo] contains multiple [Bar]s.

其中Foo和Bar均为可点击的类链接，且Bar后直接跟后缀s（无空格）。但实际操作时出现警告：

WARNING: Inline interpreted text or phrase reference start-string without end-string.

页面渲染结果不符合预期，显示为：

A [Foo] contains multiple :class:`~.Bar`s.

解决方法 #

有两种简单可行的方式实现需求：

方法1：使用显式链接文本语法 #

将链接目标与显示文本分开定义，让解析器能正确识别引用的结束位置：

A :class:`~.Foo` contains multiple :class:`Bar <~.Bar>`s.

渲染后Bar会成为指向~.Bar类的链接，后面直接跟s，无空格，符合预期效果。

方法2：使用替换定义复用链接 #

如果需要多次重复引用这些类，可先在文档合适位置（如开头）定义替换规则：

.. |Foo| replace:: :class:`~.Foo`
.. |Bar| replace:: :class:`~.Bar`

之后在正文直接使用替换标记即可：

A |Foo| contains multiple |Bar|s.

这种方式能避免重复编写链接语法，提升文档维护效率。

内容的提问来源于stack exchange，提问作者evanb