WindowsのSphinxスタンドアロン環境でSDKドキュメントを書く準備
aws-sdk-phpのドキュメントは、SphinxというPython環境で動作するツールで作られています。
PHP系なのに面白い!と思ったところ、Sphinx自体が便利なのであらゆるところに広がってるようですね。
Windowsでドキュメント書くのにSphinx環境を作るのは、何が手軽かと考えて、次の構成としてみました。スタンドアロンの特性を知らなかったので苦労したのですが、結果お手軽でいいなぁと思ってます。
- Sphinxスタンドアロン
- 各種パッケージの手動追加
手順
Sphinxスタンドアロン版のインストール
リンク先の手順にそってインストール。コマンドプロンプトを新たに起動して、pythonが動けばOK。注意点としてはデフォルトのままでインストールする場合には管理者権限が必要なのと、もともとpython入れてた人は環境変数の調整が必要になるケースもある事。
※本エントリーでは、 "c:\Program Files (x86)\Sphinx" にインストールしたとして説明します。
各種パッケージの手動追加1
次のパッケージを2つ取得します。
それぞれ解凍して、解凍したフォルダへコマンドプロンプトで移動。
各フォルダで、次のコマンドを実行し egg ファイルを作成します。
各フォルダ配下に dist フォルダが作成されて、.egg ファイルが生成されます。
各種パッケージの手動追加2
先ほど作成した .egg ファイル2つを、次のフォルダにコピー。
そして、フォルダ "C:\Program Files (x86)\Sphinx\eggs\dist" へコマンドプロンプト(管理者権限)で移動。次のコマンドを順番に実行(パッケージ名の詳細は環境依存になると思います)。
- ..\..\python\Scripts\easy_install.exe -d "C:\Program Files (x86)\Sphinx\eggs" -m .\guzzle_sphinx_theme-0.3.1-py2.7.egg
- ..\..\python\Scripts\easy_install.exe -d "C:\Program Files (x86)\Sphinx\eggs" -m .\rst2pdf-0.93.dev-py2.7.egg
依存関係の解決なども行われながら準備が完了。
各種パッケージの手動追加3
Sphinx起動時に、追加したパッケージを読み込むようにファイルを修正。メモ帳などを管理者権限で開いて行います。
sys.path[0:0]の後半に、以下を追加。
'c:\\program files (x86)\\sphinx\\eggs\\guzzle_sphinx_theme-0.3.1-py2.7.egg', 'c:\\program files (x86)\\sphinx\\eggs\\rst2pdf-0.93.dev-py2.7.egg', 'c:\\program files (x86)\\sphinx\\eggs\\reportlab-2.7-py2.7-win32.egg', 'c:\\program files (x86)\\sphinx\\eggs\\pdfrw-0.1-py2.7.egg',
以上で完成です。
その他
Sphinxの準備以外に、次の2つを実施することで make html が docsフォルダで動きます。
現段階ではソースの修正が2箇所必要
aws-sdk-php 2.4.7までの場合、Windows環境で make html するには、次のファイルを2箇所修正する必要がありました。Pull request中なので、いつかはWindowsでも修正なく通るかも!?
docs/_ext/aws/__init__.py
- 一箇所目:パスのスプリットに "/" が使われてる
- (修正前) service_path = "/".join(client_path.split("/")[0:-1])
- (修正後) service_path = "/".join(client_path.split(os.sep)[0:-1])
- 二箇所目:php -r 実行時に ' がWinでは使えない
Gitをインストール
いくつかWindows用クライアントがありますが、次のパッケージをインストールしました。(そもそも、make htmlするためにはZipでダウンロードしたaws-sdk-phpではダメで、git cloneなどで取得した作業フォルダでmake html行う必要があります。)
Downloadsページで Git-1.8.4-preview20130916.exe をダウンロードしてインストール。
コマンドプロンプトで git --version でバージョン番号が帰ってくればOK。
# GitHubのGit Shellが使えれば楽だなぁと思ったのですが、あちらはClickOnce配布形式の為、どこ参照すればいいのか分からなかった。
参考
- Sphinx-Users.jp Sphinxの日本ユーザ会
- python開発環境の構築から作成したeggを別環境へインストールするまで
- egg形式が何者かから、作成するコマンドなどの説明
- setuptools QuickStart
- setup.pyの使い方
- virtualenvなしでもプロジェクトごとのライブラリを管理する方法
- easy_installコマンドは-m (マルチバージョン)オプション の紹介を発見! .pth ファイルを回避する方法が理解できました。