概要
v4.8.1以降のLinux kernelドキュメントではSphinxが使用されています。
ここでは試しに、Ubuntu環境にSphinxを導入し、ドキュメントをビルドしてみます。
Sphinxについて
SphinxはPythonで書かれたドキュメント生成ツールです。
reStructuredText(reST)と呼ぶマークアップから、htmlやxmlなどのドキュメントを生成します。
Sphinx http://www.sphinx-doc.org/ja/stable/index.html
reStructuredText入門 http://www.sphinx-doc.org/ja/stable/rest.html
Linux kernelでは、マルチメディア系などを中心にreSTが採用されています。
Sphinxでビルドできるのは、このreSTを採用しているドキュメントです。
Sphinxの導入
Qiitaにもインストール方法がいくつか書かれているので探してみてください。
Ubuntuの場合、Sphinxのバージョンにこだわらなければ、aptで簡単にインストール可能です。
Python 2とPython 3の実装がありますが、とりあえずPython 3実装版をインストールします。
$ sudo apt install python3-sphinx
Linux kernelドキュメントのビルド
kernelのソースコードはkernel.olgのサイトからダウンロードできます。
The Linux Kernel Archives https://www.kernel.org
バージョンはv4.8.1以降ならなんでもよいですが、あまり古いとビルドでコケるようです。
(私の環境ではv4.8.1ではビルドエラーが出てうまくいきませんでした)
ここでは例として、stable版のv4.19.6で試します。
手順は簡単で、ダウンロードしたソースコードのトップディレクトリに移動し、「make htmldocs」と叩くだけです。
$ tar xaf linux-4.19.6.tar.xz
$ cd linux-4.19.6
$ ls
arch COPYING Documentation fs ipc kernel Makefile README scripts tools
block CREDITS drivers include Kbuild lib mm REPORTING-BUGS security usr
certs crypto firmware init Kconfig MAINTAINERS net samples sound virt
$ make htmldocs
SPHINX htmldocs --> file:///work/linux/linux-4.19.6/Documentation/output
PARSE include/uapi/linux/dvb/audio.h
PARSE include/uapi/linux/dvb/ca.h
=== 省略 ===
dumping object inventory... done
build succeeded, 81 warnings.
私の環境ではWARNINGがいっぱい出ますが、とりあえず無視します。
生成されたドキュメントはDocumentation/output以下に出力されます。
ウェブブラウザでDocumentation/output/index.htmlを開くと、下のようなページが読めるはずです。
中を見ていくとsvg形式の画像が含まれるなど、べたなテキストよりも随分読みやすくなる印象です。検索機能などもあり、ある程度スピーディに目的の記述まで辿れるようになっています。
他にもLaTeXやPDFなど、Sphinxのビルド時に選択できる形式で出力できます。
（別途、texliveなどのパッケージのインストールが必要です。）
「make help」で使い方を参照できます。
$ make help
=== 省略 ===
Documentation targets:
Linux kernel internal documentation in different formats from ReST:
htmldocs - HTML
latexdocs - LaTeX
pdfdocs - PDF
epubdocs - EPUB
xmldocs - XML
linkcheckdocs - check for broken external links (will connect to external hosts)
refcheckdocs - check for references to non-existing files under Documentation
cleandocs - clean all generated files
=== 省略 ===
ドキュメントのクリーン
生成したドキュメントのクリーンは「make cleandocs」を叩きます。
$ make cleandocs