如何为Sphinx的Python领域解释文本角色添加自定义HTML类

我想通过Sphinx的Python领域，手动给特定元素插入HTML类。

举个例子，我有如下文本：

Lore Ipsum :py:mod:`dataclasses`

它生成的HTML代码如下：

Lore Ipsum <a class="reference external" href="...dataclasses.html#module-dataclasses">
   <code class="xref py py-mod docutils literal notranslate">
      <span class="pre">dataclass</span>
   </code>
</a>

我希望给其中的<a>标签或<code>标签额外添加"injected"类，最终得到这样的结果：

<code class="xref py py-mod docutils literal notranslate injected">

已尝试的方案 #

"继承"角色 💥 #

.. role : injected_mod(?py:mod?)
  :class: injected

:injected_mod:`dataclasses`

问题：不知道括号里该填什么，而且此处无法使用领域，这不是一个有效的角色定义。

注册新角色 ❌ #

这种方法可行，但存在问题：我希望保留py领域原有的所有功能，重新注册角色会丢失这些特性。

向:py:领域添加角色 ❓ #

在conf.py中添加以下代码：

def setup():
   app.add_role_to_domain("py", "injected", PyXRefRole())

有效之处：会生成带有"py-injected"类的元素
问题：无法实现py:module的查找和链接功能，也就是不会生成<a class="reference external"标签。我还没找到Sphinx模块中查找功能的实现位置，也不确定是否可以扩展PyXRefRole来同时保留这两个特性。

嵌套解析/角色 😑（接近可行） #

组合角色的思路类似，comboroles扩展提供了相关解决方案。

可以通过组合角色指令来添加类：

:inject:`:py:mod:\`dataclasses\``

问题：它会在py:mod生成的块外层额外嵌套一个<span class=injected>标签，而不是直接修改现有的标签。

我不确定用嵌套解析是不是有点小题大做，但目前还没找到直接给现有标签添加额外类的方案。我觉得comboroles扩展是最有希望的方向，但不知道怎么扩展它，或者编写自定义角色函数来注入类而不是嵌套新标签。我猜测需要在自定义函数里访问并修改节点，但在这里卡住了。

备注：

• 我知道用MyST解析可以轻松实现，但目前无法全局用MyST解析这些文本。

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