如何在Sphinx搜索结果中展示deprecated标记？

要让弃用函数在Sphinx搜索结果里显示标记，你需要从模板定制和元数据索引两方面入手，具体步骤如下：

• 自定义搜索结果模板

  1. 在你的Sphinx项目根目录下新建_templates文件夹（如果没有的话），从Sphinx默认模板库中复制search.html文件到这个目录。
  2. 打开search.html，找到遍历results渲染搜索结果的代码块，在结果标题旁添加检测deprecated元数据的逻辑：

     {% if result.meta and 'deprecated' in result.meta %}
         <span style="color: #dc3545; font-weight: bold; margin-left: 8px;">⚠️ 已弃用</span>
     {% endif %}
     

     要是想统一管理样式，也可以在_static/css/custom.css里定义样式类，再在模板中引用。

• 确保弃用元数据被索引
  默认.. deprecated::标记会被Sphinx收集为元数据，但如果文档是用autodoc自动生成的，可在conf.py中添加代码确保弃用信息关联到搜索索引：

  def setup(app):
      # 确保deprecated元数据被纳入搜索结果
      app.add_config_value('html_search_options', {'include_meta': True}, 'html')
  

• 重新构建文档
  完成修改后，执行make clean && make html（或对应你的构建命令）清空旧文件并重新生成文档，此时搜索结果里的弃用函数就会带上显眼标记了。

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