Hello Absurd World!

　Pythonを使いながらTornadoやPillowのライブラリを読んでいて、きれいで見やすいなーと感じていた。特にそういったPythonの有名どころはドキュメントのスタイルが統一されていて、そのスタイルに慣れるに従ってドキュメントがなんとなくだが読みやすくなってきた。
Tornado: http://www.tornadoweb.org/en/stable/
Pillow: https://pillow.readthedocs.org/

　自作のPythonライブラリが世界展開されているサービスで使われるようになった。ありがたいのだが、そんなライブラリの使用方法の説明がGithubに上げているREADMEだけじゃ不親切に思えてきた。ドキュメント作成をしてみる。
　HTMLをごりごり書いてドキュメントを作るという手もあるが、先に出てきたTornadoなどのドキュメントがきれいで気になっていた。それらドキュメントページの下の方を見ると「Sphinxでビルドした。テーマはRead the docsのを使った」と書いてある。Sphinxで作ってRead the docsテーマを使えば真似できるらしい。Sphinx……Pythonでドキュメントと言えば、ぐらいにしか知らない。Sphinxってなんだろう。

　Sphinxはドキュメント作成ツール。.rst形式という変わった形式でドキュメントを作成していかなければならないが、例を見ながら作成していけばそれほど難しくはない。.rstで書き終えたドキュメントはHTMLやPDF、ePubなど様々な形式へビルドできる。便利。TornadoやPillowのソースと一緒に.rstで書かれたドキュメントの原型もそれぞれのGithubページで公開されているのでお手本にもあまり困らなそう。
　というわけで、
・他の著名Pythonライブラリとドキュメントのスタイルをそろえたい
・.rstというあんまり書いたことがない形式だが、HTMLだけでなくPDFやePubにも変換できる
・.rstのサンプルとしてGithubにあるTornadoやPillowなどの.rstを見れば書き方は困らなそう
と考えてSphinxを使うことにする。

　ありがたいことに日本語の普及推進ページがある。
http://sphinx-users.jp/index.html
「Sphinxをはじめよう」ページを読めばインストールから基本的な書き方、ビルドまで書いてある。それに従ってドキュメントを作成し、ビルドまで持っていく。

　Webページで公開したいのでHTMLでビルドされるようにした。そのHTMLをどこに置くかという話だが、ぼくはGithubを使っているのでGithub Pages、あるいはPillowのドキュメント他さまざまなが置いてあるRead the docsという選択肢があった。Read the docsはユーザからのドネートで運営資金がまかなわれようとしているらしいが、ありがたいことに無料で使用できる。
　Github Pagesの自分のページに置く場合は、_build\htmlにあるドキュメントをすべてコピーでもして配置する。これに加えてもう一つ、.nojekyllというからファイルを作って自分のPagesのルートに置いておく。そうしなければPagesに使われているJekyllの作用で、アンダースコアで始まるディレクトリが無視されて、スタイルやらJavaScriptが得られなくなる。ちなみにsphinxtogithubというSphinxの拡張をインストールして使うという解決法もあるが、Windowsにはインストールできない。.nojekyllのほうが手軽だった。
　GithubかBitbucketにプロジェクトを置いているなら、Read the docsにドキュメントを置かせてもらうのが手軽だろう。ぼくはGithubを使っているが、Read the docsのアカウントを取ったら、あとはGithub連携を許可して、プロジェクトをインポートするだけだった。そこからドキュメントのビルド、公開までは自動で行われた。
http://piexif.readthedocs.org/en/latest/index.html

　ドキュメントの作成から公開まで、Sphinxを使うことで一日のうちに済ませられた（ドキュメントはもっと磨く必要があるが）。便利な世の中。