Autodoc 作った
Ruby の Autodoc や Perl の Test::JsonAPI::Autodoc を真似て Python の Autodoc を作った。
GitHub - heavenshell/py-autodoc: Autodoc Python implementation.
# まだ PyPi にはアップしてないアップロードした。
もともと Jokk という Mock サーバを作った際に、レスポンスから同じようなの作ろうかなーと思ってたが、Autodoc を見てテストとして実行できるというのが素晴らしいアイディアだったので、単独のライブラリとして作った。
サンプル
# -*- coding: utf-8 -*- from unittest import TestCase from webtest import TestApp from autodoc import autodoc from tests.app import create_app class TestUnittest(TestCase): def setUp(self): app = create_app self.client = TestApp(app) @classmethod @autodoc.generate('var/test_unittest.rst') def tearDownClass(cls): pass @autodoc.describe('GET /') def test_get(self): """ GET / """ res = self.client.get('/') self.assertEqual(res.status_code, 200) return res @autodoc.describe('POST /') def test_post(self): """ POST / """ res = self.client.post_json('/', params={'id': 1, 'message': 'foo'}) self.assertEqual(res.status_code, 200) return res @autodoc.describe('POST /foo/bar') def test_foo_bar(self): """ POST /foo/bar """ res = self.client.post_json('/foo/bar', params={'id': 1, 'message': 'foo'}) self.assertEqual(res.status_code, 200) return res
上記のサンプルは UnitTest で書いてるけど、Py.Test でも使える。
試してないけど、おそらく nose も使える。
仕様として、ドキュメントを出力したいテストケースにデコレータつけて、テストケースが WebTest のレスポンスを返せばいいので、テストフレームワークに依存してない。
こんな感じで出力される。
py-autodoc/test_unittest.rst at master · heavenshell/py-autodoc · GitHub
依存ライブラリ
テストクライアントに WebTest を使ってる。
Flask や Werkzueg のテストクライアントも使えるようにしようかなーと思ったが、送信したリクエストが取得できないのでやめた。
ドキュメント生成の方法
@autodoc.describe でドキュメントを生成するテストを指定する。
@autodoc.generate でドキュメントを生成する。
1 テストケース 1 ドキュメントも出来るし、テストクラスのをまとめて 1 ファイルに出力する事もできる。
その場合 tearDownClass などのフィクスチャに @autodoc.generate をつける
出力される形式は Python なのでデフォルトは reST。
テンプレートファイルを指定すれば Markdown もいける。
テンプレートは @autodoc.generate('出力先', template='テンプレートファイル') となってるので、
template='my-template.md' とするとカレントディレクトリの my-template.md を探す。
