読者です 読者をやめる 読者になる 読者になる

AWS / PHP / Python ちょいメモ

amazon web service , PHP, Python を使ったときのメモ。日本語でググってもわからなかった事を中心に。

SDKドキュメントにcontributeしようメモ(1)

SDK ドキュメント PHP TIPS sphinx

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

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

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

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

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

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

  1. aws-sdk-php を git で fork して clone
    • zipからスタートすると、make htmlで落ちます。gitしてる箇所は一箇所なんで、そこを書き換えてもいいかも?
  2. 前出のS3のUsersGuideに該当するrstファイルをエディタで開きます
    • "aws-sdk-php\docs\service-s3.rst"
  3. 特殊そうなsphinxのdirectiveのディレクティブタイプを抽出
    • .. service:: S3
    • .. example:: S3/Integration/S3_20060301_Test.php testBucketAlreadyExists
    • 標準のディレティブは、こちらに説明あり
  4. それぞれどんなのかを "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。

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

ちゃんと書く版(他に合わせて)

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

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

ということは?

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

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