网站建立网站培训机构网站设计

上一篇博客：用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 jiebahtml_search_options = {'type': 'test','language': 'zh','tokenizer': 'jieba.sphinx_zh'}
except:pass

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

1. 中文分词的挑战

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

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

2. Jieba 分词器的角色

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

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

3. Sphinx 的索引和搜索流程

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

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

4. 关键技术与优化

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

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

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

6. 实际依赖和扩展

安装 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

2. 配置模板路径

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

templates_path = ['_templates']

3. 覆盖现有模板

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

<!-- source/_templates/footer.html -->
<div class="footer">© 2025 @yeshen.org | 自定义页脚内容
</div>

4. 扩展现有模板（继承并修改）
   使用Jinja2的 {% extends %} 继承原模板，然后覆盖特定块。

示例：在侧边栏添加内容

<!-- source/_templates/sidebar.html -->
{% extends "!sidebar.html" %}{% block sidebarlogo %}{{ super() }}  <!-- 保留原有内容 --><div class="custom-sidebar-section">你的自定义内容</div>
{% endblock %}

5. 创建全新模板

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

6. 使用自定义模板

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～