Welcome to Autodoc’s documentation!

What is Autodoc

Generate documentation from your unit-test.

This library is Python implementation of Autodoc.

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

Conventions

Return WebTest or requests response in test method

Py-Autodoc must return WebTest response or requests 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.

Indices and tables