awspecのソースコードやオブジェクトからドキュメントを生成する

awspecはAWSのリソース構成をServerspecのようにテストするためのテスティングフレームワークです。

ServerspecにおけるResource Typeは、awspecにおけるAWSの各リソースになります。

今回、awspecのリソースタイプのドキュメントを作るにあたって、ソースコードやオブジェクトからドキュメントを半自動生成する機能を実装してみました。

生成したリソースタイプのドキュメントはこちら。

マッチャはオブジェクトから収集して、そのマッチャの説明文章は別のファイルに書いたものをマージして生成しています。

具体的には、git cloneしたディレクトリ内で

$ bundle exec lib/awspec/bin/toolbox docgen > doc/resource_types.md

とすれば更新できるようにしました。

これで、マッチャやリソースタイプが作られた時点で、マッチャやリソースタイプの存在だけは手軽にドキュメントに追記できるし、必要に応じて後から説明文章を追加すれば良いという安心感があります。

また、awspecのバックエンドはAWS謹製のaws-sdk-rubyなのですが、aws-sdk-rubyで取得したrawデータは膨大な情報を持っています（describe_*なメソッド）。

awspecはその情報をメタ的に利用してマッチャ( its(:xxx) { } 系)を生成しています。なので、aws-sdk-rubyがアップデートされて、さらに多くの情報を取得できるようになったときも、動的にマッチャ情報を追記できます。

ドキュメントの生成について

もともとはansible.elをつくった時に気づいたのですが、Ansibleはソースコード内にドキュメントの元となるYAMLを記述しています。

awspecも、Ansibleとは違うちょっとトリッキーな方法になりましたが、ある程度ドキュメント生成が実現できたので満足です。