Sphinx渲染:ref:链接时自动添加斜体样式，如何去除该效果？

刚遇到这个问题的时候我也头疼过，Sphinx默认给:ref:类型的链接文本加上斜体样式，确实不符合很多场景的需求，不过有两种简单的方法可以解决：

方法一：通过自定义CSS覆盖样式 #

这是最直接的方案，因为Sphinx生成HTML时，:ref:链接的文本会被<em>标签包裹，我们只需要用CSS把这个标签的斜体样式取消掉就行：

• 在你的Sphinx项目的_static文件夹下创建一个自定义CSS文件，比如命名为custom.css
• 在conf.py中添加配置，让Sphinx加载这个自定义CSS：

  html_css_files = ['custom.css']
  

• 在custom.css里写入以下样式：

  /* 针对所有ref链接里的em标签取消斜体 */
  a.reference em {
      font-style: normal;
  }
  

  这样所有:ref:生成的链接文本都会变成正常字体，不会有斜体了。

方法二：自定义无斜体的引用角色 #

如果你不想修改全局样式，也可以自定义一个新的rst角色，用来生成不带斜体的引用链接：

• 在项目的conf.py中添加以下代码：

  from docutils import nodes
  from docutils.parsers.rst import roles
  
  def no_italic_ref(name, rawtext, text, lineno, inliner, options={}, content=[]):
      # 解析类似"显示文本 <目标标签>"的格式
      if ' ' in text:
          display_text, target = text.split(' ', 1)
          target = target.strip('<>')
      else:
          display_text = text
          target = text
      # 创建不带em标签的引用节点
      ref_node = nodes.reference(rawtext, display_text, refname=target, **options)
      return [ref_node], []
  
  # 注册名为noref的自定义角色
  roles.register_local_role('noref', no_italic_ref)
  

• 之后在你的rst文档里，就可以用:noref:create 来代替原来的`:ref:`create <create-title>，这样生成的链接文本就不会有斜体样式了。

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