0x00 Kernal与rst
Linux kernal的文档使用rst结构化文本编写，阅读kernal\msm-4.1.4\README文档可知，可以通过
make htmldocs
生成可读的html
那就试一试，果然报错了
HOSTCC scripts/basic/fixdep
Documentation/Makefile:24: The 'sphinx-build' command was not found. Make sure you have Sphinx installed and in PATH, or set the SPHINXBUILD make variable to point to the full path of the 'sphinx-build' executable.
Detected OS: Ubuntu 14.04.5 LTS.
Warning: better to also install "convert".
Warning: better to also install "dot".
Warning: better to also install "dvipng".
Warning: better to also install "rsvg-convert".
ERROR: please install "virtualenv", otherwise, build won't work.
Warning: better to also install "xelatex".
You should run:
sudo apt-get install imagemagick graphviz dvipng librsvg2-bin virtualenv texlive-xetex
virtualenv sphinx_1.4
. sphinx_1.4/bin/activate
pip install -r Documentation/sphinx/requirements.txt
google一下，关键在于sphinx，这是一个python写的生成格式化文档的工具。提示很清晰，那就一个个安装吧。因为是离线环境下的生产环境，所以步骤稍微麻烦。
0x01 步骤
virtualenv
根据错误描述，virtualenv是必须的，先安装其他的，没有问题：
sudo apt-get install imagemagick graphviz dvipng librsvg2-bin texlive-xetex
但安装 virtualenv 时出现：
现在没有可用的软件包 virtualenv，但是它被其它的软件包引用了。
这可能意味着这个缺失的软件包可能已被废弃，
或者只能在其他发布源中找到
可是下列软件包取代了它：
python-pip-whl
到Pypi上找一下：
https://pypi.org/project/virtualenv/
下载whl包 virtualenv-16.2.0-py2.py3-none-any.whl 安装即可
python3 -m pip install virtualenv-16.2.0-py2.py3-none-any.whl
sphinx
按照上面的方式设置虚拟环境的命令就可用了，接下来需要安装sphinx，提示使用的命令是：pip install -r Documentation/sphinx/requirements.txt 但这是在在线环境下自动下载的。
因此参考这篇里 https://www.jianshu.com/p/fc6e75a2858b 离线安装pip的步骤，这里只列出步骤，不作解释。
- 在线机上：requirements.txt文件就是kernel目录下的Documentation/sphinx/requirements.txt
python -m pip download -r requirements.txt -d e:\sphinx_require
- 下载 Linux 版本的MakeupSafe，因为其区分操作系统
https://pypi.org/project/MarkupSafe/#files
MarkupSafe-1.1.0-cp37-cp37m-manylinux1_x86_64.whl
- 指定离线包的安装sphinx
python3 -m pip install -r Documentation/sphinx/requirements.txt --no-index --find-links=~/sphinx_require
生成文档
这时再次运行
make htmldocs
就能在kernel/msm-4.14/Documentation/output下查看生成的html文档了
0x02 结语
在 https://www.kernel.org/doc/html/latest/index.html 也能查看到官方生成的文档，现在你也可以学着定制自己的kernel文档了
网友评论