Linux内核自带说明文档的优雅阅读工具的安装使用方法

本文约1100字，我准备开始走读内核驱动源码了，先做一下准备工作，下载好内核源码，而后将内核自带的说明文档充分利用起来，内核文档多是.rst格式，还有少量.txt和.md,

用记事本或notepad++打开，可读性不佳。本文将介绍内核文档的优雅阅读的工具安装使用方法。

关注公众号, 即可获得与Linux相关的电子书籍以及常用开发工具，文末有文档清单。

本文根据两大场景来构建阅读环境(源码编译环境基于Ubuntu 18.04.6 LTS, 内核版本为6.1.161)：

注意：先搭建好环境，ubuntu虚拟机联网，需要下载安装特定工具。下载好内核源码linux-6.1.161.tar.xz并解压。

一 系统学习内核文档

构建内核文档的HTML 版（最美观、最系统）

这是阅读内核文档的最优解:

内核源码中内置了Sphinx构建脚本，无需手动配置，安装依赖后一键构建，生成的 HTML 页面有层级目录、超链接、代码高亮、搜索功能，和官方在线内核文档（kernel.org/doc/html）完全一致，本地阅读无网络限制，还能和本地源码版本严格对应。

步骤1：安装构建依赖

内核文档构建依赖Python3 + Sphinx + 相关渲染库 + 内核构建基础依赖

，执行对应发行版的安装命令：

sudo apt update && sudo apt install -y python3-sphinx python3-sphinx-rtd-theme python3-pip make gcc libelf-dev libssl-dev rst2pdf # 补充安装内核文档专用的Sphinx扩展（部分内核版本需要）pip3 install sphinx-tabs sphinxcontrib-programoutput

步骤2：一键构建 

构建HTML版文档进入内核源码根目录（假设为linux-6.1.161/，需和你本地的内核版本一致），执行内核内置的构建命令，无需配置任何Sphinx文件

（内核已封装好）：

# 进入内核源码根目录cd linux-6.6/ #构建HTML版文档（核心命令，一键执行）make htmldocs

说明：推荐使用make htmldocs 2>/dev/null || true来忽略编译过程的警告。

注意：如果编译过程中报错如下：

Can't build as 2 mandatory dependencies are missing at ./scripts/sphinx-pre-install line 1005.Documentation/Makefile:95: recipe for target 'htmldocs' failedmake[1]: *** [htmldocs] Error 2Makefile:1826: recipe for target 'htmldocs' failedmake: *** [htmldocs] Error 2

解决方法：安装完整的依赖库

执行命令查看需要安装哪些依赖库

./scripts/sphinx-pre-install

我的环境提示如下：

根据提示，执行apt-get install dvipng latexmk librsvg2-bin texlive-lang-chinese texlive-xetex

重新执行make htmldocs 2>/dev/null || true，编译完后，进入output目录下用浏览器打开.html文件，如index.html，页面展示如下：

这样就很方便阅读文档了，可搜索可进行链接。

二 边看源码边看文档

VS Code/Vim + 对应 rst 插件同屏查看、源码 - 文档联动

需要安装官方推荐的插件reStructuredText和reStructuredText Syntax highlighting，这个我没有试，有兴趣的可以安装尝试下。