如何在python-sphinx中实现文本背景色高亮？

嘿，我之前也在Sphinx里折腾过单个文本背景高亮的需求，试了几个实用的方案，分享给你：

方法1：自定义RST角色+CSS（推荐，适配多输出格式） #

这个方法是最灵活的，后续调整样式只改CSS就行，还能适配大部分支持CSS的输出格式。

步骤如下：

1. 在conf.py里注册自定义角色
   打开项目根目录的conf.py，添加这段代码：

   from docutils.parsers.rst import roles
   from docutils.nodes import Element, Text
   
   def bg_highlight_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
       node = Element()
       node['classes'] = ['bg-highlight']
       node.append(Text(text))
       return [node], []
   
   roles.register_local_role('bg-highlight', bg_highlight_role)
   

   这段代码注册了一个叫bg-highlight的自定义角色，会给目标文本加上指定的CSS类。

2. 添加自定义CSS样式
   先在项目的_static目录下新建custom.css文件（如果没有_static就自己创建一个），然后写入样式：

   .bg-highlight {
       background-color: #ffff00; /* 这里可以换成你想要的背景色，比如#ffcccc是浅红 */
       padding: 0 3px;
       border-radius: 2px; /* 可选，让边角更圆润 */
   }
   

   接着在conf.py里把这个CSS文件加入到HTML输出的资源里：

   html_css_files = [
       'custom.css',
   ]
   

3. 在文档中使用
   不管是RST还是MyST Markdown文档，都可以这样用：

   • RST： :bg-highlight:需要高亮背景的文本``
   • MyST：{bg-highlight}需要高亮背景的文本``

方法2：直接嵌入HTML（快速但仅适配HTML输出） #

如果你的Sphinx项目只需要输出HTML格式，那可以直接用HTML标签快速实现，不用改配置：

• RST里用raw指令：

  .. raw:: html
  
      <span style="background-color: #ffff00; padding: 0 3px;">需要高亮背景的文本</span>
  

• MyST Markdown里更简单，直接写HTML就行：

  <span style="background: yellow; padding: 0 3px;">需要高亮背景的文本</span>
  

  这个方法的缺点是如果要生成PDF等其他格式，这段HTML会被忽略，所以只适合纯HTML输出的场景。

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