简介这套《Linux内核文档》离线HTML压缩包是一份面向Linux开发者、内核学习者与系统管理员的参考手册适合需要通读内核机制、查阅接口或准备编写设备驱动与内核模块的人群。文档围绕核心子系统展开既有体系结构、进程管理、内存管理的原理讲解也覆盖虚拟文件系统挂载、字符与块设备驱动、PCI及USB总线机制、TCP/IP与socket接口、SELinux安全模型、模块加载API以及kdb、kgdb、sysfs、procfs等调试工具与技巧便于与内核源码对照阅读也可在无网络环境下离线查阅适合按章节精读或作为速查手册。压缩包约23.03MB内容以HTML文档形式组织方便本地查阅上游未提供具体文件清单不影响直接解压使用。目前已有131人学习/下载对希望理解Linux底层运作、定制和裁剪内核、优化系统性能、编写驱动或排查疑难问题的开发者与管理员具有很高的参考价值。1. 拿到 The Linux Kernel documentation.zip 之后先想清楚三件事从名字就能看出这是一个把 Linux 内核 Documentation/ 目录打包好的文档压缩包常见于内网离线环境、课程资料分发和面试前的集中复习。它的好处是零门槛不需要配置 Sphinx、不需要编译内核解压就能读但风险也在打包人手里第三方做的 Zip 经常和你手上的内核版本对不上旧版文档里写死的 sysctl 与驱动 API到新版内核里可能已经改名或删除。所以我拿到这种包的第一反应不是急着解压而是先确认三件事包内对应哪个内核版本、文件列表里有没有 index.rst 这类 RST 入口、它是否真的来自官方源码树。下面从验证开始把一条能落地的路径完整走一遍。2. 内核文档树的结构、来源与版本对应关系2.1 先看清单Documentation/ 下这些年没动的骨架任何一个合格的内核文档包顶层都会有一个 index.rst它是整棵文档树的根节点也是 Sphinx 构建时的入口。根节点之下各子系统按目录分家路径与源码树里的 drivers/、mm/ 大体对应好处是从代码跳文档时不用猜。拿到 zip 后我建议第一件事就是列一遍清单对照下表认目录目录 / 文件覆盖内容适合谁admin-guide/内核编译、模块加载、启动参数运维与内核编译者process/开发流程、编码风格、提交流程内核贡献者core-api/内存、refcount、per-cpu 等核心 API底层开发driver-api/USB、PCI、GPIO 等驱动框架驱动开发admin-guide/kernel-parameters.rst全部内核启动参数排错与调优scheduler/、mm/、locking/调度、内存、锁机制面试与原理分析需要说明的是同一份文档在不同年份的打包者手里路径常有微调。启动参数全表曾经是 Documentation/kernel-parameters.txt后来迁到 admin-guide/ 下改名 kernel-parameters.rstREADME 也从源码树顶层挪进了 admin-guide/。如果你手里的包还在用旧路径基本可以判断它是按 4.x 甚至更早的树整理的这时候别把它当成 6.x 的接口词典只适合理解通用机制。2.2 从 kernel.org 拉源码导出纯净文档包想给自己留一份干净、可信的文档 zip最好的来源是官方源码树而不是网上二次整理的版本。常见做法是用 kernel.org 的 tar.xz解压后只取 Documentation/ 目录再重新打包# 下载官方压缩包和独立签名文件 wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.6.tar.xz wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.6.tar.sign # 导入维护者公钥指纹以 kernel.org 发布页为准 gpg --locate-keys torvaldskernel.org gregkhkernel.org # .sign 是对未压缩 tar 的签名先还原 tar 再验签 xz -dc linux-6.6.tar.xz linux-6.6.tar gpg --verify linux-6.6.tar.sign linux-6.6.tar # 记录哈希作为与第三方包比对的底账 sha256sum linux-6.6.tar.xz # 只抽取 Documentation重新打包成 zip mkdir -p ~/linux-docs tar -xJf linux-6.6.tar.xz -C ~/linux-docs --strip-components1 \ linux-6.6/Documentation cd ~/linux-docs zip -r linux-6.6-documentation.zip Documentation参数说明tar 的 -xJf 组合里J 表示输入是 xz 压缩f 指定文件名--strip-components1 去掉顶层 linux-6.6/ 目录避免解压后目录套目录zip -r 递归打包整个目录。验签环节最容易出错的地方在于 .sign 只覆盖未压缩的 tar 流所以必须先 xz -dc 还原出 tar再执行 gpg --verify直接拿 .tar.xz 去验签必败这是流程里最容易载跟头的一步。提示对 .tar.xz 直接验签会失败。torvaldskernel.org 的签名覆盖的是未压缩 tar 流必须 xz -dc 还原后再 gpg --verify。公钥导入后还要和 kernel.org 发布页公布的指纹核对一遍这是 gpg 信任链里绕不开的动作。只从公开 keyserver 导入并不等于可信指纹对不上时宁可放弃这次下载。2.3 版本匹配文档包必须绑定内核版本内核文档不是通用的离线书它是跟着源码树走的说明性产物。启动参数、sysctl、tracepoint 经常在小版本之间改名4.19 的文档指导不了 6.6 的调优。判断手上 zip 对应哪个版本常见做法是看内部路径官方导出通常保留 linux-x.y/ 前缀二手工整理则会在顶层放 README 或 VERSION 文件。用 unzip -p 快查一个关键文件就能定位unzip -p The_Linux_Kernel_documentation.zip \ Documentation/admin-guide/README.rst | head -30unzip -p 不落盘直接把条目内容打到标准输出适合这种快查。README 开头几行通常会写 Linux kernel release 6.6 之类的版本声明如果包里没有 README就拿 Documentation/Makefile 或顶部 index.rst 的生成时间做参照。本地环境版本用 uname -r 看源码树里用 make kernelversion。场景上WSL2 用户自己编译内核、或者面对高通 CAF 这类厂商定制分支时同样要按分支对号——主线 zip 只能解释通用机制不能当成厂商接口的准确定义。3. 解压、查看与乱码处理打开文档 zip 的完整命令路径3.1 解压前必做三步file、unzip -l、unzip -t文档 zip 出问题多数发生在解压之前而不是之后。最常见的两种下载被中断扩展名还是 .zip内容只剩一半打包工具把非 zip 文件直接改了后缀。所以解压前花十秒做三个只读检查file The_Linux_Kernel_documentation.zip # 看真实格式 unzip -l The_Linux_Kernel_documentation.zip # 看清单确认有 index.rst unzip -t The_Linux_Kernel_documentation.zip # 逐个条目校验 CRCfile 输出 Zip archive data 说明格式没问题输出 RAR 或 HTML说明后缀是假的直接回源头重新下载。unzip -l 除了列清单还能看到压缩比文档类纯文本的压缩比通常很高如果看到平铺几千个同名文件先怀疑打包错误。unzip -t 逐个校验 CRC任何一条 failed 都说明这个包不可信别舍不得删。需要落盘时的参数见下表参数作用典型场景-d 目录指定解压目标目录防止文件撒得满目录都是-O 编码指定文件名源编码处理 GBK 压的包-p 条目内容直接打到 stdout不解压快看单个文件-n不覆盖已存在文件重复解压时保旧-q安静模式脚本里减少输出3.2 文件名乱码zip 编码机制与 unzip -O 参数老 zip 规范用 OEM 代码页记录文件名后来的实现靠 UTF-8 flag 标明编码。Windows 中文环境压出来的包文件名常是 GBKLinux 的 unzip 默认按 UTF-8 解码解出来就是满屏乱码。unzip 6.0 起多数发行版编译时带了 iconv用 -O 指定源编码即可unzip -O gbk The_Linux_Kernel_documentation.zip -d ~/kernel-docs-O gbk 让 unzip 按 GBK 解释文件名并转成 UTF-8 落盘-d 指定解压目录防止几百个文件摊得到处都是。如果手里的 unzip 不支持 -O编译时没开 iconv退路是 p7zip-full 的 7z x它对编码的容忍度更高。注意unzip 6.0 的 -O 参数依赖编译时开启 iconv个别精简发行版没带先用 unzip -hh 确认再依赖它。反过来说官方内核文档的文件名全是 ASCII一份正经导出、没被再加工的 zip 根本不该有乱码。出现乱码说明文件被第三方工具重写过版本一致性要重新评估这一点比乱码本身更值得警惕。3.3 损坏的 zip遇到 could not find eocd 怎么处理could not find eocd 是 zip 解析库共用的报错文案eocd 指 End Of Central Directoryzip 文件末尾的中央目录记录。报这个错基本只有三种原因文件被截断、后缀名是假的、读取方不支持 ZIP64。先用 file 和 ls 排除后两种再按顺序抢救ls -lh The_Linux_Kernel_documentation.zip zip -FF The_Linux_Kernel_documentation.zip --out docs-fixed.zip 7z x The_Linux_Kernel_documentation.zipzip -FF 重建中央目录结果写到 --out 指定的新文件-FF 比 -F 更彻底但更慢文档这类必须保证完整的包用 -FF日志类可以容忍局部损坏的就用 -F。7z x 对尾部缺失的容忍度比 unzip 高能解多少算多少抢救出的单篇文档往往还有阅读价值。若 file 直接识别出这是 HTML 或二进制说明根本不是 zip修复没意义换个下载源成本更低。把 zip 操作排进 linux 常用命令清单unzip -t、zip -FF、7z x 这一组基本覆盖九成损坏场景。4. 自己构建一套与源码同步的内核文档Sphinx 与 make htmldocs4.1 为什么最终要自己构建第三方 zip 是快照快照必然过期。内核文档的母本是源码树里那批 .rstdocs.kernel.org 上能看到的全部内容都由它们构建。自己构建的收益有三个版本严格对应当前源码Sphinx 产出的 HTML 带交叉引用、侧栏目录和全文搜索阅读效率比在纯文本里翻高很多内核新增的文档章节只有母本里有zip 里见不到。代价是环境配一次之后每次内核版本更新只是一条 make 命令的事。4.2 最小构建装依赖、跑 make htmldocs构建文档不涉及编译内核不需要交叉工具链是纯粹的 Sphinx 流程。Debian/Ubuntu 系一条 apt 装齐不想污染系统 Python 就用 venv 隔离sudo apt install python3-sphinx python3-sphinx-rtd-theme \ texlive-latex-extra texlive-fonts-recommended librsvg2-bin python3 -m venv ~/sphinx-venv source ~/sphinx-venv/bin/activate pip install sphinx sphinx_rtd_theme cd linux-6.6 make htmldocs # 产物在 Documentation/output/html/浏览器打开 index.htmlmake htmldocs 是内核 Kbuild 提供的文档目标会先跑一次版本检查确认当前 Sphinx 版本落在此内核支持的区间内。不同内核版本要求不一样较新的主线一般要求 Sphinx 3.4.6 以上但太新的版本也常被拦下报错里会直接给出当前版本和要求区间按提示在 venv 里把 sphinx 固定到对应小版本即可。依赖包用途见下表依赖包用途python3-sphinxSphinx 本体python3-sphinx-rtd-themeRead the Docs 主题内核默认皮肤texlive-latex-extraPDF 输出需要的 LaTeX 组件librsvg2-binSVG 图形转 PDF 的渲染器只做 htmldocs 可省4.3 out-of-tree 构建、并行参数与常见报错源码树和构建产物分开是内核一贯的习惯文档构建同样支持 Omake O/tmp/kbuild htmldocs make htmldocs SPHINXOPTS-j 4O 把 Documentation/output 挪到独立目录源码树保持干净git status 不会被构建产物刷屏。SPHINXOPTS 原样透传给 sphinx-build-j 4 按 CPU 核数调想安静就加 -q。构建到一半想停直接 Ctrl-C 即可sphinx-build 留下的临时目录下一次构建会覆盖不需要手动清理O 目录想整个推倒重来rm -rf /tmp/kbuild 也比在源码树里清 .o 文件省心。4.3.1 三个高频报错No module named sphinx_rtd_theme主题没装pip install sphinx_rtd_theme 即好和 Sphinx 本体无关。Sphinx 版本不在支持区间看报错给出的区间venv 里固定版本重装。pdfdocs 报 LaTeX 错误对照 4.2 的 texlive 一行补齐别只装 texlive-base。排查时注意区分输出里的 WARNING 和 ERRORWARNING 多来自 RST 语法过期或交叉引用失效不影响产物ERROR 才会中止构建。老内核配新 Sphinx 的经典场面是 WARNING 刷屏但构建能过处理方式是回归到该内核文档说明的版本而不是硬扛。5. 把文档 zip 变成检索工具固定文件与版本核对技巧5.1 两个固定优先读的文件不管文档包是谁打的这两个文件都建议最先读Documentation/admin-guide/README.rst 是编译与安装内核的官方入口Documentation/admin-guide/kernel-parameters.rst 是启动参数字典排错先搜它。准备 linux 面试题的话按 scheduler/、mm/、locking/ 三个目录顺读正好覆盖调度、内存、并发三块高频考点比在论坛看二手的八股文可靠。5.2 一行命令核对 zip 与源码版本用 rg 做全文检索# 全文检索启动参数查 mitigations 相关项 rg -n mitigations \ ~/kernel-docs/Documentation/admin-guide/kernel-parameters.rst # diff 无输出 zip 内文件与源码树一致 diff (unzip -p The_Linux_Kernel_documentation.zip \ Documentation/admin-guide/README.rst) \ linux-6.6/Documentation/admin-guide/README.rstdiff 的左右两侧分别是 zip 内条目和源码树文件进程替换 () 省去临时文件。无输出说明这个 zip 对应的就是当前源码版本有差异则以源码为基准别迷信 zip 里的打包时间。验证做完之后Debian/Ubuntu 还有一条更省事的长期方案apt install linux-doc文档装在 /usr/share/doc/linux-doc/ 下启动参数字典一般以 kernel-parameters.txt.gz 形式躺在里面zless 直接翻。升级内核后重跑一次上面的 diff 核对命令有差异就重新导出这份 zip 才能作为长期使用的检索基线继续留存。本文还有配套的精品资源点击获取
简介这套《Linux内核文档》离线HTML压缩包是一份面向Linux开发者、内核学习者与系统管理员的参考手册适合需要通读内核机制、查阅接口或准备编写设备驱动与内核模块的人群。文档围绕核心子系统展开既有体系结构、进程管理、内存管理的原理讲解也覆盖虚拟文件系统挂载、字符与块设备驱动、PCI及USB总线机制、TCP/IP与socket接口、SELinux安全模型、模块加载API以及kdb、kgdb、sysfs、procfs等调试工具与技巧便于与内核源码对照阅读也可在无网络环境下离线查阅适合按章节精读或作为速查手册。压缩包约23.03MB内容以HTML文档形式组织方便本地查阅上游未提供具体文件清单不影响直接解压使用。目前已有131人学习/下载对希望理解Linux底层运作、定制和裁剪内核、优化系统性能、编写驱动或排查疑难问题的开发者与管理员具有很高的参考价值。1. 拿到 The Linux Kernel documentation.zip 之后先想清楚三件事从名字就能看出这是一个把 Linux 内核 Documentation/ 目录打包好的文档压缩包常见于内网离线环境、课程资料分发和面试前的集中复习。它的好处是零门槛不需要配置 Sphinx、不需要编译内核解压就能读但风险也在打包人手里第三方做的 Zip 经常和你手上的内核版本对不上旧版文档里写死的 sysctl 与驱动 API到新版内核里可能已经改名或删除。所以我拿到这种包的第一反应不是急着解压而是先确认三件事包内对应哪个内核版本、文件列表里有没有 index.rst 这类 RST 入口、它是否真的来自官方源码树。下面从验证开始把一条能落地的路径完整走一遍。2. 内核文档树的结构、来源与版本对应关系2.1 先看清单Documentation/ 下这些年没动的骨架任何一个合格的内核文档包顶层都会有一个 index.rst它是整棵文档树的根节点也是 Sphinx 构建时的入口。根节点之下各子系统按目录分家路径与源码树里的 drivers/、mm/ 大体对应好处是从代码跳文档时不用猜。拿到 zip 后我建议第一件事就是列一遍清单对照下表认目录目录 / 文件覆盖内容适合谁admin-guide/内核编译、模块加载、启动参数运维与内核编译者process/开发流程、编码风格、提交流程内核贡献者core-api/内存、refcount、per-cpu 等核心 API底层开发driver-api/USB、PCI、GPIO 等驱动框架驱动开发admin-guide/kernel-parameters.rst全部内核启动参数排错与调优scheduler/、mm/、locking/调度、内存、锁机制面试与原理分析需要说明的是同一份文档在不同年份的打包者手里路径常有微调。启动参数全表曾经是 Documentation/kernel-parameters.txt后来迁到 admin-guide/ 下改名 kernel-parameters.rstREADME 也从源码树顶层挪进了 admin-guide/。如果你手里的包还在用旧路径基本可以判断它是按 4.x 甚至更早的树整理的这时候别把它当成 6.x 的接口词典只适合理解通用机制。2.2 从 kernel.org 拉源码导出纯净文档包想给自己留一份干净、可信的文档 zip最好的来源是官方源码树而不是网上二次整理的版本。常见做法是用 kernel.org 的 tar.xz解压后只取 Documentation/ 目录再重新打包# 下载官方压缩包和独立签名文件 wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.6.tar.xz wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.6.tar.sign # 导入维护者公钥指纹以 kernel.org 发布页为准 gpg --locate-keys torvaldskernel.org gregkhkernel.org # .sign 是对未压缩 tar 的签名先还原 tar 再验签 xz -dc linux-6.6.tar.xz linux-6.6.tar gpg --verify linux-6.6.tar.sign linux-6.6.tar # 记录哈希作为与第三方包比对的底账 sha256sum linux-6.6.tar.xz # 只抽取 Documentation重新打包成 zip mkdir -p ~/linux-docs tar -xJf linux-6.6.tar.xz -C ~/linux-docs --strip-components1 \ linux-6.6/Documentation cd ~/linux-docs zip -r linux-6.6-documentation.zip Documentation参数说明tar 的 -xJf 组合里J 表示输入是 xz 压缩f 指定文件名--strip-components1 去掉顶层 linux-6.6/ 目录避免解压后目录套目录zip -r 递归打包整个目录。验签环节最容易出错的地方在于 .sign 只覆盖未压缩的 tar 流所以必须先 xz -dc 还原出 tar再执行 gpg --verify直接拿 .tar.xz 去验签必败这是流程里最容易载跟头的一步。提示对 .tar.xz 直接验签会失败。torvaldskernel.org 的签名覆盖的是未压缩 tar 流必须 xz -dc 还原后再 gpg --verify。公钥导入后还要和 kernel.org 发布页公布的指纹核对一遍这是 gpg 信任链里绕不开的动作。只从公开 keyserver 导入并不等于可信指纹对不上时宁可放弃这次下载。2.3 版本匹配文档包必须绑定内核版本内核文档不是通用的离线书它是跟着源码树走的说明性产物。启动参数、sysctl、tracepoint 经常在小版本之间改名4.19 的文档指导不了 6.6 的调优。判断手上 zip 对应哪个版本常见做法是看内部路径官方导出通常保留 linux-x.y/ 前缀二手工整理则会在顶层放 README 或 VERSION 文件。用 unzip -p 快查一个关键文件就能定位unzip -p The_Linux_Kernel_documentation.zip \ Documentation/admin-guide/README.rst | head -30unzip -p 不落盘直接把条目内容打到标准输出适合这种快查。README 开头几行通常会写 Linux kernel release 6.6 之类的版本声明如果包里没有 README就拿 Documentation/Makefile 或顶部 index.rst 的生成时间做参照。本地环境版本用 uname -r 看源码树里用 make kernelversion。场景上WSL2 用户自己编译内核、或者面对高通 CAF 这类厂商定制分支时同样要按分支对号——主线 zip 只能解释通用机制不能当成厂商接口的准确定义。3. 解压、查看与乱码处理打开文档 zip 的完整命令路径3.1 解压前必做三步file、unzip -l、unzip -t文档 zip 出问题多数发生在解压之前而不是之后。最常见的两种下载被中断扩展名还是 .zip内容只剩一半打包工具把非 zip 文件直接改了后缀。所以解压前花十秒做三个只读检查file The_Linux_Kernel_documentation.zip # 看真实格式 unzip -l The_Linux_Kernel_documentation.zip # 看清单确认有 index.rst unzip -t The_Linux_Kernel_documentation.zip # 逐个条目校验 CRCfile 输出 Zip archive data 说明格式没问题输出 RAR 或 HTML说明后缀是假的直接回源头重新下载。unzip -l 除了列清单还能看到压缩比文档类纯文本的压缩比通常很高如果看到平铺几千个同名文件先怀疑打包错误。unzip -t 逐个校验 CRC任何一条 failed 都说明这个包不可信别舍不得删。需要落盘时的参数见下表参数作用典型场景-d 目录指定解压目标目录防止文件撒得满目录都是-O 编码指定文件名源编码处理 GBK 压的包-p 条目内容直接打到 stdout不解压快看单个文件-n不覆盖已存在文件重复解压时保旧-q安静模式脚本里减少输出3.2 文件名乱码zip 编码机制与 unzip -O 参数老 zip 规范用 OEM 代码页记录文件名后来的实现靠 UTF-8 flag 标明编码。Windows 中文环境压出来的包文件名常是 GBKLinux 的 unzip 默认按 UTF-8 解码解出来就是满屏乱码。unzip 6.0 起多数发行版编译时带了 iconv用 -O 指定源编码即可unzip -O gbk The_Linux_Kernel_documentation.zip -d ~/kernel-docs-O gbk 让 unzip 按 GBK 解释文件名并转成 UTF-8 落盘-d 指定解压目录防止几百个文件摊得到处都是。如果手里的 unzip 不支持 -O编译时没开 iconv退路是 p7zip-full 的 7z x它对编码的容忍度更高。注意unzip 6.0 的 -O 参数依赖编译时开启 iconv个别精简发行版没带先用 unzip -hh 确认再依赖它。反过来说官方内核文档的文件名全是 ASCII一份正经导出、没被再加工的 zip 根本不该有乱码。出现乱码说明文件被第三方工具重写过版本一致性要重新评估这一点比乱码本身更值得警惕。3.3 损坏的 zip遇到 could not find eocd 怎么处理could not find eocd 是 zip 解析库共用的报错文案eocd 指 End Of Central Directoryzip 文件末尾的中央目录记录。报这个错基本只有三种原因文件被截断、后缀名是假的、读取方不支持 ZIP64。先用 file 和 ls 排除后两种再按顺序抢救ls -lh The_Linux_Kernel_documentation.zip zip -FF The_Linux_Kernel_documentation.zip --out docs-fixed.zip 7z x The_Linux_Kernel_documentation.zipzip -FF 重建中央目录结果写到 --out 指定的新文件-FF 比 -F 更彻底但更慢文档这类必须保证完整的包用 -FF日志类可以容忍局部损坏的就用 -F。7z x 对尾部缺失的容忍度比 unzip 高能解多少算多少抢救出的单篇文档往往还有阅读价值。若 file 直接识别出这是 HTML 或二进制说明根本不是 zip修复没意义换个下载源成本更低。把 zip 操作排进 linux 常用命令清单unzip -t、zip -FF、7z x 这一组基本覆盖九成损坏场景。4. 自己构建一套与源码同步的内核文档Sphinx 与 make htmldocs4.1 为什么最终要自己构建第三方 zip 是快照快照必然过期。内核文档的母本是源码树里那批 .rstdocs.kernel.org 上能看到的全部内容都由它们构建。自己构建的收益有三个版本严格对应当前源码Sphinx 产出的 HTML 带交叉引用、侧栏目录和全文搜索阅读效率比在纯文本里翻高很多内核新增的文档章节只有母本里有zip 里见不到。代价是环境配一次之后每次内核版本更新只是一条 make 命令的事。4.2 最小构建装依赖、跑 make htmldocs构建文档不涉及编译内核不需要交叉工具链是纯粹的 Sphinx 流程。Debian/Ubuntu 系一条 apt 装齐不想污染系统 Python 就用 venv 隔离sudo apt install python3-sphinx python3-sphinx-rtd-theme \ texlive-latex-extra texlive-fonts-recommended librsvg2-bin python3 -m venv ~/sphinx-venv source ~/sphinx-venv/bin/activate pip install sphinx sphinx_rtd_theme cd linux-6.6 make htmldocs # 产物在 Documentation/output/html/浏览器打开 index.htmlmake htmldocs 是内核 Kbuild 提供的文档目标会先跑一次版本检查确认当前 Sphinx 版本落在此内核支持的区间内。不同内核版本要求不一样较新的主线一般要求 Sphinx 3.4.6 以上但太新的版本也常被拦下报错里会直接给出当前版本和要求区间按提示在 venv 里把 sphinx 固定到对应小版本即可。依赖包用途见下表依赖包用途python3-sphinxSphinx 本体python3-sphinx-rtd-themeRead the Docs 主题内核默认皮肤texlive-latex-extraPDF 输出需要的 LaTeX 组件librsvg2-binSVG 图形转 PDF 的渲染器只做 htmldocs 可省4.3 out-of-tree 构建、并行参数与常见报错源码树和构建产物分开是内核一贯的习惯文档构建同样支持 Omake O/tmp/kbuild htmldocs make htmldocs SPHINXOPTS-j 4O 把 Documentation/output 挪到独立目录源码树保持干净git status 不会被构建产物刷屏。SPHINXOPTS 原样透传给 sphinx-build-j 4 按 CPU 核数调想安静就加 -q。构建到一半想停直接 Ctrl-C 即可sphinx-build 留下的临时目录下一次构建会覆盖不需要手动清理O 目录想整个推倒重来rm -rf /tmp/kbuild 也比在源码树里清 .o 文件省心。4.3.1 三个高频报错No module named sphinx_rtd_theme主题没装pip install sphinx_rtd_theme 即好和 Sphinx 本体无关。Sphinx 版本不在支持区间看报错给出的区间venv 里固定版本重装。pdfdocs 报 LaTeX 错误对照 4.2 的 texlive 一行补齐别只装 texlive-base。排查时注意区分输出里的 WARNING 和 ERRORWARNING 多来自 RST 语法过期或交叉引用失效不影响产物ERROR 才会中止构建。老内核配新 Sphinx 的经典场面是 WARNING 刷屏但构建能过处理方式是回归到该内核文档说明的版本而不是硬扛。5. 把文档 zip 变成检索工具固定文件与版本核对技巧5.1 两个固定优先读的文件不管文档包是谁打的这两个文件都建议最先读Documentation/admin-guide/README.rst 是编译与安装内核的官方入口Documentation/admin-guide/kernel-parameters.rst 是启动参数字典排错先搜它。准备 linux 面试题的话按 scheduler/、mm/、locking/ 三个目录顺读正好覆盖调度、内存、并发三块高频考点比在论坛看二手的八股文可靠。5.2 一行命令核对 zip 与源码版本用 rg 做全文检索# 全文检索启动参数查 mitigations 相关项 rg -n mitigations \ ~/kernel-docs/Documentation/admin-guide/kernel-parameters.rst # diff 无输出 zip 内文件与源码树一致 diff (unzip -p The_Linux_Kernel_documentation.zip \ Documentation/admin-guide/README.rst) \ linux-6.6/Documentation/admin-guide/README.rstdiff 的左右两侧分别是 zip 内条目和源码树文件进程替换 () 省去临时文件。无输出说明这个 zip 对应的就是当前源码版本有差异则以源码为基准别迷信 zip 里的打包时间。验证做完之后Debian/Ubuntu 还有一条更省事的长期方案apt install linux-doc文档装在 /usr/share/doc/linux-doc/ 下启动参数字典一般以 kernel-parameters.txt.gz 形式躺在里面zless 直接翻。升级内核后重跑一次上面的 diff 核对命令有差异就重新导出这份 zip 才能作为长期使用的检索基线继续留存。本文还有配套的精品资源点击获取
