Autodoc Python implementation.
Generate documentation from your unit-test.
.. image:: https://travis-ci.org/heavenshell/py-autodoc.png?branch=master
This library is Python implementation of Autodoc.
Autodoc <https://github.com/r7kamura/autodoc>
_Test::JsonAPI::Autodoc <https://metacpan.org/pod/Test::JsonAPI::Autodoc>
_Repository <https://github.com/heavenshell/py-autodoc>
_Documentation <http://autodoc.readthedocs.org/en/latest/>
_::
$ virtualenv --distribute autodoc_sample $ source autodoc/bin/activate $ cd autodoc $ pip install autodoc
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
::
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.
::
@pytest.fixture def setup(): setup = TestApp(create_app)
return setup
@autodoc.generate('var/testpytest.md', template='templates/markdown.md') def teardownmodule(module): pass
@autodoc.describe('POST /') def testpost(setup): res = setup.postjson('/', params={'id': 1, 'message': 'foo'}) assert res.status_code == 200
return res
::
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
Return WebTest or requests response in test method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Py-Autodoc must return WebTest response.
::
@autodoc.describe('POST /') def testpost(setup): res = setup.postjson('/', 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.
You can configure @autodoc.generat(output, template=path_to_template)
to change template file.