如何将Sphinx的cssclass类添加到锚点span而非section元素？

默认情况下，Sphinx的.. cssclass::指令是绑定到后续的<section>元素上的，没法直接让它把类加到锚点<span>标签上。不过可以通过两种方式实现需求：

• 自定义HTML模板
  找到Sphinx使用的模板文件（通常是layout.html或章节相关的模板片段），修改锚点span的渲染逻辑。比如找到模板里生成锚点的代码，让它读取当前章节的cssclass属性并添加到span标签上。
  示例修改：
  原模板代码可能类似：

  <span id="{{ anchorname }}"></span>
  

  修改为：

  <span id="{{ anchorname }}" class="{{ section.cssclass }}"></span>
  

  把修改后的模板放到项目的_templates目录下，Sphinx会优先使用自定义模板。

• 编写简易Sphinx扩展
  写一个小扩展，在HTML生成阶段处理文档树，把section的cssclass转移到对应锚点span上。比如借助html-page-context事件实现：

  def transfer_cssclass(app, pagename, templatename, context, doctree):
      if doctree:
          for section in doctree.traverse(lambda node: hasattr(node, 'css_class')):
              if section.css_class:
                  # 遍历HTML输出找到对应锚点span，添加类名
                  # 可结合BeautifulSoup等工具处理HTML内容
                  pass
  def setup(app):
      app.connect('html-page-context', transfer_cssclass)
  

  将这个扩展保存为Python文件，在项目的conf.py中注册该扩展即可。

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