linux制作html文档,生成Kernel文档（转换rst为阅读友好的html）

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 结语