SDKドキュメントにcontributeしようメモ(1) - AWS / PHP / Python ちょいメモ

aws-sdk-php v2のUserGuideドキュメント、Auto Scaling, Amazon Elastic Compute Cloud, Amazon Elastic MapReduce, Amazon Glacier など、まだincomplete（完成してない）ものがチラホラあります。

API referenceを見れば使えるので、そこまで困りませんが、やはり始めの取っ掛かりとしては敷居が高いと思います。S3とかはUserGuideに結構助けられたし。

ということで、contribute出来ないか探ってみました。

※UsersGuideは、PythonのSphinxというドキュメントビルダーで書かれています。Sphinxの環境構築は、このエントリーやらWebの情報を参考に構築いただければと思い、割愛します。

構造を探ってみる: S3を参考に

S3のUsersGuideを参考に、構造を探ってみました。

aws-sdk-php を git で fork して clone
- zipからスタートすると、make htmlで落ちます。gitしてる箇所は一箇所なんで、そこを書き換えてもいいかも？
前出のS3のUsersGuideに該当するrstファイルをエディタで開きます
- "aws-sdk-php\docs\service-s3.rst"
特殊そうなsphinxのdirectiveのディレクティブタイプを抽出
- .. service:: S3
- .. example:: S3/Integration/S3_20060301_Test.php testBucketAlreadyExists
- 標準のディレティブは、こちらに説明あり
それぞれどんなのかを "def setup(app)" が含まれる "docs\_ext\aws\__init__.py" で見てみる
- service ディレクティブタイプ
  - "src\Aws\Common\Resources\aws-config.php" と "src\Aws\S3\Resources\s3-2006-03-01.php" の array を解析して作成
- example ディレクティブタイプ
  - "tests\Aws\Tests" 配下のファイルを参照。"aws-sdk-php\tests\Aws\Tests\S3\Integration\S3_20060301_Test.php" の testBucketAlreadyExists 関数
  - 指定関数の中から、3つの特殊コメント " }\n", " // @begin\n", " // @end\n" をキーにコードを抜き出し

UsersGuideを書く手順

先ほどのものをベースに考えてみました。

とりあえず版

Testsコードは必須じゃないと考える場合、書くだけなればこれだけでOK。

UsersGuideを書くサービスを選ぶ
該当するrstファイルを編集

ちゃんと書く版（他に合わせて）

でも、S3を見る分には、Testsコードを再利用する形が良さそう。そう考えると、次の手順が必要かな。

UsersGuideを書くサービスを選ぶ
該当サービスのTestsコードをのぞく
Testsコードを使ってUsresGuideが書けそうかを検討
不足してるようなればTestsコードを追加
該当するrstファイルを編集

ということは？

Testsコードを置くということは、CIとかで実行されるという理解？

もしそうなれば、rstの為とはいえ、ちゃんとした動くTestsコードを用意しないといけなくなりますね。自身の中で、ちょっとハードルが上がりましたが、またトライしてみます。