如何自定义Python Sphinx搜索以支持关键词限定？

要实现输入METHOD fill时优先或仅展示名称包含fill的方法，你可以通过以下两种方式实现，核心是利用Sphinx的搜索扩展能力：

1. 利用html_search_scorer自定义评分逻辑 #

Sphinx的html_search_scorer是官方提供的搜索评分钩子，虽然官方文档覆盖较少，但可以通过操作搜索索引中的文档元数据来调整结果排序。

编写步骤 #

在你的Sphinx项目的conf.py中添加以下自定义评分函数：

def html_search_scorer(doc, query):
    score = 0.0
    query_parts = query.strip().split(maxsplit=1)
    
    # 解析带限定词的查询（如 METHOD fill）
    if len(query_parts) == 2:
        qualifier, keyword = query_parts
        qualifier = qualifier.upper()
        
        # 处理METHOD类型限定
        if qualifier == "METHOD":
            # 给匹配的方法文档大幅加分
            if doc.get("objtype") == "method" and keyword.lower() in doc.get("objname", "").lower():
                score += 15.0
            # 非方法文档减分，降低优先级
            elif doc.get("objtype") != "method":
                score -= 10.0
        
        # 可扩展其他限定词（如 CLASS、FUNCTION）
        elif qualifier == "CLASS":
            if doc.get("objtype") == "class" and keyword.lower() in doc.get("objname", "").lower():
                score += 15.0
            elif doc.get("objtype") != "class":
                score -= 10.0
    
    # 保留基础全文匹配得分（标题匹配权重高于正文）
    target_keyword = query_parts[-1].lower() if query_parts else query.lower()
    if target_keyword in doc.get("title", "").lower():
        score += 4.0
    if target_keyword in doc.get("text", "").lower():
        score += 1.0
    
    return score

可用文档元数据字段 #

搜索索引中的doc对象包含以下常用字段（可通过在函数中加入print(doc.keys())查看完整字段）：

• objtype: API对象类型（如method、function、class、module，仅autodoc生成的文档存在）
• objname: API对象名称（如方法名fill）
• title: 文档标题
• text: 文档正文内容
• uri: 文档的相对URL路径

效果说明 #

• 当输入METHOD fill时，名称包含fill的方法文档会获得最高得分，优先排在搜索结果顶部
• 若要实现“仅展示”，可将不符合条件的文档得分设为负数（如score = -99.0），这类结果会被排到最底部，几乎不会被看到

2. 修改前端JS实现精确过滤 #

如果需要更严格的“仅展示”效果，可以修改Sphinx的前端搜索逻辑：

1. 复制Sphinx默认的searchtools.js文件到你的项目静态资源目录（可通过查找Sphinx安装目录下的_static文件夹获取）
2. 在文件中找到处理搜索结果的逻辑（通常是Search.prototype.showResults方法）
3. 添加解析限定词的代码，过滤掉不符合类型的结果：

// 示例：在结果展示前加入过滤逻辑
if (query.includes("METHOD ")) {
    const keyword = query.split("METHOD ")[1];
    results = results.filter(item => {
        // objtype存储在item.attributes.objtype中
        return item.attributes.objtype === "method" && item.attributes.objname.toLowerCase().includes(keyword.toLowerCase());
    });
}

4. 在conf.py中配置静态资源路径，让项目使用自定义的searchtools.js：

html_static_path = ['_static']
html_js_files = ['searchtools.js']

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