autodoc 0.5.0

Description:

autodoc 0.5.0

Generate documentation from your unit-test.

This library is Python implementation of Autodoc.

Autodoc
Test::JsonAPI::Autodoc


Links

Repository
Documentation



Installation
$ virtualenv --distribute autodoc_sample
$ source autodoc/bin/activate
$ cd autodoc
$ pip install autodoc


Usage
Run unittest with PYAUTODOC=1 to generate documents for your tests decorated with @autodoc.generate.
PYAUTODOC=1 python -m unittest examples/test_unittest.py
If you use py.test as test runner.
PYAUTODOC=1 py.test tests examples/test_pytest.py
If you use nose as test runner.
PYAUTODOC=1 nosetests tests examples/test_unittest.py


Example for unittest
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() describe test name.
For example GET / assigned to generated document.
@autodoc.generate(path_to_output) will generate document.


Example for py.test
@pytest.fixture
def setup():
setup = TestApp(create_app)

return setup


@autodoc.generate('var/test_pytest.md', template='templates/markdown.md')
def teardown_module(module):
pass


@autodoc.describe('POST /')
def test_post(setup):
res = setup.post_json('/', params={'id': 1, 'message': 'foo'})
assert res.status_code == 200

return res


Example for requests
import requests

class TestUnittest(TestCase):
def setUp(self):
self.client = requests

@classmethod
@autodoc.generate('var/test_unittest.rst')
def tearDownClass(cls):
pass

@autodoc.describe('POST /')
def test_post(self):
""" POST / """
params = {'id': 1, 'message': 'foo'}
headers = {'content-type': 'application/json'}
res = self.client.post('http://example.com/',
data=params, headers=headers)
self.assertEqual(res.status_code, 200)

return res


Conventions

Return WebTest or requests response in test method
Py-Autodoc must return WebTest response.
@autodoc.describe('POST /')
def test_post(setup):
res = setup.post_json('/', params={'id': 1, 'message': 'foo'})
assert res.status_code == 200

return res # Must return WebTest or requests response.


Generate document point
@autodoc.generate will create document.
If you set @autodoc.generate to each test case, document will generate each file.
class TestUnittest(TestCase):
def setUp(self):
app = create_app
self.client = TestApp(app)

@autodoc.generate('var/indext_get.rst')
@autodoc.describe('GET /')
def test_get(self):
""" GET / """
res = self.client.get('/')
self.assertEqual(res.status_code, 200)

return res

@autodoc.generate('var/foo_get.rst')
@autodoc.describe('GET /foo')
def test_get(self):
""" GET / """
res = self.client.get('/foo')
self.assertEqual(res.status_code, 200)

return res
This will generate var/index_get.rst and var/foo_get.rst.
If you want to generate all tests into single file,
decorate @autodoc.generate to tearDownClass, teardown_module fixture.



Configuration
You can configure @autodoc.generat(output, template=path_to_template) to change template file.