【Python】sphinxでAPIドキュメントを作る

みんなお仕事で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言語で指定したけど、他にもいろんな言語に対応してるくさい。

とまぁ、ひとまず、こんだけの機能があれば既存のドキュメントからの移植はできそう。ほかにも色々できそうなポテンシャル秘めてるので時間あるときに弄り倒してみようかね。

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

日本語が含まれない投稿は無視されますのでご注意ください。(スパム対策)