Autodoc

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>_

Links

Repository <https://github.com/heavenshell/py-autodoc>_
Documentation <http://autodoc.readthedocs.org/en/latest/>_

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/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

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 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.

Configuration

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