Linux内核文档构建失败：make xmldocs报错如何解决？

核心问题分析 #

• 顶层目录执行make xmldocs报错是因为缺少Sphinx相关构建依赖；
• 进入Documentation目录执行报错是因为构建脚本依赖顶层目录的路径，不能在子目录直接运行。

分步解决步骤 #

1. 安装必需的构建依赖 #

内核文档构建依赖Sphinx及配套组件，根据你的Linux发行版执行对应安装命令：

• Debian/Ubuntu：

  sudo apt install python3-sphinx python3-sphinx-rtd-theme python3-docutils
  

• RHEL/CentOS/Fedora：

  sudo dnf install python3-sphinx python3-sphinx_rtd_theme python3-docutils
  

• Arch Linux：

  sudo pacman -S python-sphinx python-sphinx-rtd-theme python-docutils
  

2. 回到内核顶层目录执行构建 #

必须在你克隆的Linux内核仓库根目录下运行构建命令，不要进入Documentation子目录：

make xmldocs

3. 额外排查（若仍有报错） #

• 确认Python版本：内核文档构建仅支持Python 3，执行python --version检查，若默认是Python 2，需确保系统优先使用Python 3，或调整脚本调用的Python版本；
• 更新仓库代码：如果克隆的是较早版本的内核仓库，执行git pull拉取最新代码，避免旧脚本的兼容性问题；
• 修复脚本权限：若提示sphinx-pre-install无执行权限，执行以下命令添加权限：

  chmod +x scripts/sphinx-pre-install
  

内容的提问来源于stack exchange，提问作者user129393192