Skip to content

sphinx-docs

Sphinx doc

上一篇博客：用sphinx-doc整理文档
回头看，上一篇博客已经是18年的事情了。最近我又开始维护起18年的项目了。最近策划同事提了一些需求。我又改进了一波，所以有本文。

sphinx支持导出pdf

sphinx本身是支持导出pdf的，命令如下：

make clean latexpdf

支持中文的话，需要在 conf.py 增加如下信息：

language = 'zh_CN'
# https://sphinx-rtd-trial.readthedocs.io/en/1.0.8/config.html
# support chinese
latex_elements = {
    'preamble': r'''
    \hypersetup{unicode=true}
    \usepackage{CJKutf8}
    \DeclareUnicodeCharacter{00A0}{\nobreakspace}
    \DeclareUnicodeCharacter{2203}{\ensuremath{\exists}}
    \DeclareUnicodeCharacter{2200}{\ensuremath{\forall}}
    \DeclareUnicodeCharacter{2286}{\ensuremath{\subseteq}}
    \DeclareUnicodeCharacter{2713}{x}
    \DeclareUnicodeCharacter{27FA}{\ensuremath{\Longleftrightarrow}}
    \DeclareUnicodeCharacter{221A}{\ensuremath{\sqrt{}}}
    \DeclareUnicodeCharacter{221B}{\ensuremath{\sqrt[3]{}}}
    \DeclareUnicodeCharacter{2295}{\ensuremath{\oplus}}
    \DeclareUnicodeCharacter{2297}{\ensuremath{\otimes}}
    \begin{CJK}{UTF8}{gbsn}
    \AtEndDocument{\end{CJK}}
    ''',
    'extraclassoptions': 'openany,oneside',
}

需要安装如下几个软件：

apt-get install -y texlive-fonts-recommended texlive-fonts-extra
apt-get install -y texlive-latex-extra latexmk latex-cjk-all

PS：这几个软件都有点大，增加的时候注意看看是否需要。

sphinx支持中文搜索

需要安装这个分词软件

pip install jieba

需要在 conf.py 增加如下信息：

try:
    import jieba
    html_search_options = {
        'type': 'test',
        'language': 'zh',
        'tokenizer': 'jieba.sphinx_zh'
    }
except:
    pass

在 Sphinx 搜索引擎中配置 'tokenizer': 'jieba.sphinx_zh' 以支持中文搜索，其核心原理是通过集成 中文分词技术 和 搜索引擎的索引机制，将中文文本拆解为有意义的词语单元，从而实现对中文内容的精准检索。以下是具体实现原理的分步解释：

  1. 中文分词的挑战

中文文本没有像英文那样的空格分隔符，因此需要借助分词工具将连续的字序列切分为独立的词语。例如：

原始文本："我爱自然语言处理" 分词结果：["我", "爱", "自然语言处理"] 或 ["我", "爱", "自然", "语言", "处理"]（取决于分词模式） 分词质量直接影响搜索的准确性和召回率。错误的分词（如 "自然语" 和 "言处理"）会导致搜索失败。

  1. Jieba 分词器的角色

Jieba 是一个高效的中文分词工具，提供以下能力：

精确模式：将句子最精确地切分（适合文本分析）。 全模式：扫描所有可能的词语组合（速度快，可能冗余）。 搜索引擎模式：在精确模式基础上，对长词再次切分（适合检索场景）。 在 Sphinx 中，jieba.sphinx_zh 模块是专门为 Sphinx 设计的适配接口，使其能够调用 Jieba 的分词功能。

  1. Sphinx 的索引和搜索流程

配置 tokenizer: jieba.sphinx_zh 后，Sphinx 的工作流程如下：

索引阶段（Indexing） 文本预处理：读取文档中的中文文本。 调用 Jieba 分词：使用 Jieba 将文本切分为词语列表。例如： 输入："清华大学位于北京" 分词结果：["清华大学", "位于", "北京"] 构建倒排索引：将分词后的词语作为索引项（terms），记录它们在文档中的位置和频率，形成倒排索引结构。 搜索阶段（Searching） 用户输入查询：例如 "北京 大学"。 查询分词：Jieba 将查询词切分为 ["北京", "大学"]。 匹配倒排索引：Sphinx 查找包含这些词语的文档，计算相关性并返回结果。

  1. 关键技术与优化

词典机制：Jieba 内置核心词典（如 dict.txt），包含常见词语及其词频，确保基础分词的准确性。用户也可扩展自定义词典（如添加专业术语 "自然语言处理"）。 算法优化： 基于前缀词典的贪婪匹配：最大化匹配长词（如优先匹配 "清华大学" 而非 "清华" + "大学"）。 隐马尔可夫模型（HMM）：识别未登录词（如人名、机构名）。 停用词过滤：Sphinx 可配置忽略常见无意义词（如 "的"、"了"），减少索引冗余。 词性标注（可选）：通过 Jieba 的词性标注功能，实现更细粒度的搜索过滤（如仅搜索名词）。

  1. 为何需要显式配置 Tokenizer？

Sphinx 默认使用基于空格和标点的简单分词（适合英文），无法处理中文连续文本。通过替换为 jieba.sphinx_zh，Sphinx 的底层分词逻辑被重定向到 Jieba 的接口，从而支持中文语义单元的分词。

  1. 实际依赖和扩展

安装 Jieba：需通过 pip install jieba 安装库，并确保 Sphinx 能调用 Python 模块。 自定义词典：可通过 jieba.load_userdict("custom_dict.txt") 添加领域专有词汇。 性能调优：调整 Jieba 的缓存机制和并行分词模式，以提升索引速度。

总的来说，通过集成 Jieba 分词器，Sphinx 将中文文本转化为有意义的词语单元，解决了中文全文检索的核心难题。这一配置直接影响了索引构建和查询处理的底层逻辑，使 Sphinx 能够像处理英文一样高效地支持中文搜索，核心依赖分词准确性和搜索引擎的倒排索引技术

sphinx支持自定义样式/JS

需要在 conf.py 增加如下信息：

html_static_path = ['_static']
html_js_files = ['yeshen.js','yeshen_1.js']
html_css_files = ['yeshen.css']

创建 _static 目录，然后在其中增加 yeshen.js yeshen.css yeshen_1.js 等几个文件 这几个文件会在生成的index.html中引用。

目录说明：

conf.py
_static
    |-- yeshen.js
    |-- yeshen.css
    |__ yeshen_1.js

sphinx支持自定义模版

  1. 创建模板目录

在项目根目录下创建 _templates 文件夹：

mkdir source/_templates
  1. 配置模板路径

在 　conf.py 中指定模板路径：

templates_path = ['_templates']
  1. 覆盖现有模板

查找目标模板：确定你要修改的模板文件（如 layout.html, footer.html 等）。参考你所使用的主题的模板结构。 创建同名文件：在 _templates 下创建同名文件，Sphinx将优先使用你的模板。 示例：修改页脚（覆盖 footer.html）

<!-- source/_templates/footer.html -->
<div class="footer">
    © 2025 @yeshen.org | 自定义页脚内容
</div>
  1. 扩展现有模板（继承并修改） 使用Jinja2的 {% extends %} 继承原模板，然后覆盖特定块。

示例：在侧边栏添加内容

<!-- source/_templates/sidebar.html -->
{% extends "!sidebar.html" %}

{% block sidebarlogo %}
    {{ super() }}  <!-- 保留原有内容 -->
    <div class="custom-sidebar-section">
        你的自定义内容
    </div>
{% endblock %}
  1. 创建全新模板

在 _templates 中新建文件，并通过 .. template:: 指令在RST中引用。

  1. 使用自定义模板

HTML主题：确保 conf.py 中设置了正确的主题（如 html_theme = 'alabaster'）。 构建文档：

sphinx-build -b html source build

常用模板文件 layout.html: 整体布局 header.html: 页眉 footer.html: 页脚 sidebar.html: 侧边栏 page.html: 单页内容 提示 使用 sphinx-build -b html source build 重新生成文档以查看更改。 查看主题的原始模板文件（如经典主题模板）获取可覆盖的块名。 通过以上步骤，你可以灵活定制Sphinx文档的样式和结构

sphinx支持单页面

多页面的场景下，切换导航的时候，页面会跳动，体验不是很好，sphinx支持编译单页面，可以这样做：

make clean singlehtml

但是观察单页面输出的场景，搜索栏不见了。

~~怎么添加搜索栏还要进一步尝试，本文就不展开了~~

尾声

如果还有下一篇博客的话，应该是怎么定制自己的模版了。：）

have fun～