みんなお仕事でAPIのドキュメント作るのってどうしてんだろう。WordとかExcelで作った事はあるんだけど、ちょいちょいレイアウト崩れたりしてムキーッてなる。wikiをHTMLにエクスポートして配布というのも長いこと続けてたけれど、リファレンス作るツールとして特化してるわけじゃないから痒いところに手が届かなかったり。
てな感じで悶々と過ごしてた明くる日、pythonのリファレンス眺めてたら右下になんか書いてあるのが目に入った。Sphinx…？通りかかる人に意地悪なクイズ出して、間違えたら食べちゃう怪異かな？なんかよくわからんけど凄そうだ（小並感）
といったところでsphinxについて調べてみると、色々な言語向けのドキュメントを作れるツールらしいゾ。これを使わない手は無いぜ。あ、ちなみに例のごとく会社のPCがWindows縛りなのでWindows環境で。
環境のセットアップ
セットアップは、基本的に公式のチュートリアルどおりやればOK。
>pip install sphinx
>sphinx-quickstart
すると、なんか英語で色々と質問される。俺の英語力では何喋ってるのかさっぱどわがんねので、感覚で答えてく。よくわからん項目はそのままEnter押してどうぞ。
Project name:apidoc ←たぶんプロジェクトの名前(初期ページに表示される) Author name: kabineko ←たぶん作った人 Project language[en]: ja ←日本語使うよ
他の質問はアホのフリしてハイハイ言っておけば、Windows向けのmake用batファイルまで作ってくれる至れり尽くせり感。
続けて、次のコマンドを打ち込んでみる。
>make html
Running Sphinx v1.7.5 loading translations [ja]... done making output directory... loading pickled environment... not yet created building [mo]: targets for 0 po files that are out of date building [html]: targets for 1 source files that are out of date updating environment: 1 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... genindex writing additional pages... search copying static files... done copying extra files... done dumping search index in Japanese (code: ja) ... done dumping object inventory... done build succeeded. The HTML pages are in _build\html.
すると、なんかめっちゃ頑張ってる感じのログが出てくる。どーやら、_build\html に成果物が出力されたようだ。build/html/index.html をブラウザで開いてみようか。
すっごーい！でもそっけなーい！なんかこのまま使うのは気に食わないので、conf.py をテキストエディタで弄っていろいろカスタマイズすることに。
見た目のカスタマイズ
まずはデフォルトのテーマがいくつか用意されてるので、テキトーなやつを選んでみた。
html_theme = 'alabaster'
こいつを
html_theme = 'sphinxdoc'
こう変える。
他にも気になる所があるので色々カスタマイズ。
html_show_sourcelink = False
なんか、デフォルトだとページの生データ見せるリンクがあったのだが、いらんので非表示に。
html_show_copyright = False
コピーライトは表示させたくない。社内向けの資料だから不要な情報やろね。
html_show_sphinx = False
「このドキュメントはSphinxで生成しました」てな表示がケツに出るので抑制。俺以外は興味無いだろうし。
html_use_index = False
「索引」が表示されてるけど別に使わんしなぁ。消せ消せぇ！
html_theme_options = {
'nosidebar': True,
}
サイドバーメニューまでテコ入れするのが面倒なので、テーマオプションで消しておく。
結果、こんな感じになった。だいぶスッキリした。一瞬「索引」消えて無くね？って思ったけど、画面右下とか右上とか常に表示されてるリンクが消えるだけなので、本文のスクリプト弄れば消えるっぽい。
ドキュメントを弄る
おもむろにindex.rst をテキストエディタで開いてみる。
うーん、さっぱどわがんね！どーやら、reStructuredText(reST)というマークアップ言語で書くらしい。詳しくは公式のドキュメント見るのがてっとり早そうだ。
とりあえず、APIの一覧表とチュートリアルのページを作ってみたいので、こんな感じで書いてみた。
大項目、中項目の見出しをバーンってやったあとにtoctreeで目次のツリーを表示する。
で、api/api_list.rst と tutorial/tutorial.rst を用意して、タイトルだけ書いておく。
まずは、api/api_list.rst。
=============================================== API一覧 ===============================================
次に、tutorial/tutorial.rst。
=============================================== チュートリアル ===============================================
で、再び make html。
すると、こんな感じで各ページに書いたタイトルを勝手に拾い出して、メニューに表示してくれる。ウホッ
API一覧表を作る
さっき作ったAPI一覧に、APIの個別ページへのリンクを追記してみる。なんかrestで表組みの作り方は色々あるっぽいけれども、csvテーブルが個人的が楽そうだなと思った。外部リンクは :doc:’表示テキスト <パス>’みたいな感じで貼れるくさい。
結果、こうなった。いいじゃん！
APIの個別ページを作る
こんな感じで、コードブロックを記述してみる。
言語のキーワードをハイライト表示してくれる。今回はC言語で指定したけど、他にもいろんな言語に対応してるくさい。
とまぁ、ひとまず、こんだけの機能があれば既存のドキュメントからの移植はできそう。ほかにも色々できそうなポテンシャル秘めてるので時間あるときに弄り倒してみようかね。