Edited at

Sphinxの導入とLinux Kernelドキュメントのビルド


概要

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を開くと、下のようなページが読めるはずです。

linux_v4.19.6_Documentaion.png

中を見ていくと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