Sphinx中文搜索

安装 jieba 模块
pip install jieba

  • 修改 conf.py 配置，将项目设置为中文，或者html搜索语言设置为中文:

配置Sphinx conf.py 设置项目为中文
language = 'zh_CN'
#html_search_language = 'zh'

  • 可选配置:

可选配置 jieba 词典路径
# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
# html_search_options = {'dict': '/usr/lib/jieba.txt'}   # 根据需要设置jieba的词典路径

排查

有一段时间不知道什么变化导致 Read the Docs编译缓慢的解决建议 ，我通过关闭中文language来恢复快速编译。当时就发现搜索功能已经失效了，不论在搜索框中输入中文还是英文，回车以后就看到页面上有一个 search... 没有任何输出。

经过很久很久，我终于发现(2024年底)，应该是某次升级Sphinx之后，很久以前的Sphinx旧版本 conf.py 配置有很多不兼容的残留配置导致无法正常生成搜索索引文件。解决的方法也很简单，就是用最新的Sphinx重新创建一个空的project，获得干净的 conf.py 文件，再手工将需要的配置(参考现在的)添加回去，这样再次 make html 就能正常生成搜索索引文件，最终恢复了搜索功能。

  • source/conf.py 配置修订如下:

重新简化生成新版本正确的 conf.py
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import sphinx_rtd_theme

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Cloud Atlas: Discovery'
copyright = '2018 - now, Huatai Huang'
author = 'Huatai Huang'
release = 'beta'
version = '1.1'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
        'sphinx.ext.graphviz',
        'sphinxnotes.strike',
        'sphinxcontrib.youtube',
        'sphinxcontrib.video',
        'myst_parser'
]

# -- GraphViz configuration ----------------------------------
graphviz_output_format = 'svg'

templates_path = ['_templates']
exclude_patterns = []

language = 'zh'
html_search_language = 'zh'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

#html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"
html_static_path = ['_static']
html_favicon = '_static/favicon.png'

参考