Python の日本語ドキュメントをdashで利用できる形式に変換する(doc2dashを利用する)

Last updated at 2015-11-15Posted at 2015-11-15

Macで利用できるドキュメントビューア（スニペット管理も出来るらしいです）にDashというアプリがあります。

このDashにPythonのドキュメントも登録できますが、日本語ドキュメントは（当然ですが）ありません。

過去にトライされた方がいまして、参考にさせていただきました。

日本語ドキュメントのsphinxを利用する

トライされた方は、日本語ドキュメントのHTMLをそのまま利用したようです。その場合、モジュールや関数と言った個別のインデックスが作れないという問題がありました。そのため、今回はsphinxのドキュメントコードをクローンして作成しました。

virtualenvでsphinxとdoc2dashをインストールします。dashの公式でdoc2dashの使い方がありましたのでそちらをほぼまるまる引用です。

なお、今回はpython 3.4.3(Mac Yosemite, homebrew)で作成しました。2.7でdoc2dashを行うとUnicodeDecodeError的な嫌なものが出てきたので、避けるためにpy3kです

$ python --version
python 3.4.3 

$ mkvirtualenv cpydoc-ja-doc2dash
(cpydoc-ja-doc2dash)$ pip install sphinx doc2dash

日本語ドキュメントのリポジトリは、bitbucketにあるようです。

hgのリポジトリなので、hgでcloneして下さい。sourcetreeを使ったのでコマンドは割愛します（汗）
また、ブランチでタグの3.4でチェックアウトしています。

ビルドするときに、Sphinxの国際化対応のビルド方法で行う必要があります。以下を参考にしました。

(cpydoc-ja-doc2dash)$ cd <path/to/cpython-ja_repo>/Doc

(cpydoc-ja-doc2dash)$ make -e SPHINXOPTS="-D language='de'" html

doc2dashを使って生成します。

(cpydoc-ja-doc2dash)$ doc2dash -n Python3.4jp -i build/html/_static/py.png -d ~/Documents/ build/html/

これで、ホームディレクトリの~/Documents/内に、Python3.4jp.docsetという

なお、doc2dashのexampleにある、doc2dashのオプション -a はDashアプリに自動的に追加するオプションです。

生成されたdocsetファイルをダブルクリックすればDash上に登録されます。

sphinxから生成したhtmlを利用すると、検索類も綺麗に出してくれます。非常に便利なのでPythonistaな方々はぜひともチャレンジしてみてください！日本語翻訳プロジェクトの皆様に感謝です

要望がありましたら生成したファイルをアップしても良いのですが、権利的に良いのかわからないので何方か教えて（汗）