如何在Sphinx中为Python类引用设置自定义文本并明确指向类而非同名章节

我来帮你梳理下这个问题的解决方案，刚好之前也遇到过类似的情况：

核心问题原因 #

你之前的几种写法踩了两个坑：

• Custom Text <:py:class:MyClass>：这种写法相当于把:py:class:角色嵌套进了普通链接文本里，Sphinx不会解析里面的角色语法，自然失效；
• Custom Text<MyClass>：Sphinx在解析这种无类型的交叉引用时，会优先匹配文档内的章节标题，所以才会跳转到同名章节，而不是Python类。

最直接的解决方案：用ref指定Python类的目标标识符 #

Sphinx会给每个Python对象（包括你手动写的:py:class:MyClass``）自动生成一个唯一的内部引用目标，格式是py:class:+类的完整标识（如果是模块内的类，要加上模块路径）。

你只需要用标准的ref角色来引用这个目标，同时指定自定义文本，就能实现标准交叉引用样式（同字体、蓝色下划线），还能明确指向Python类：

:ref:`自定义文本 <py:class:MyClass>`

如果你的类属于某个模块（比如my_module.MyClass），最好加上完整路径避免重名：

:ref:`自定义文本 <py:class:my_module.MyClass>`

这种写法既不用手动加锚点，又能精准区分Python类和同名章节，样式也完全符合你的需求。

备选方案：手动添加自定义锚点（适合复杂场景） #

如果你的类需要被多次引用，或者类名太长，也可以用你考虑过的手动加锚点的方式，不过要注意锚点要放在类定义的正上方：

.. _myclass-custom-ref:

:py:class:`MyClass`
    这里是类的文档内容...

然后引用时用：

:ref:`自定义文本 <myclass-custom-ref>`

这种方式更灵活，尤其是当你需要给同一个类设置多个不同的引用锚点时很有用。

为什么:py:class:Custom text``样式不对？ #

因为:py:系列角色本身自带特殊的样式（比如等宽字体），它的设计初衷是展示代码元素的标识，而不是做普通的交叉引用，所以渲染出来的样式和标准链接不一样，这也是为什么不推荐用这种写法的原因。

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