html+轉換+rst,生成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 結語