Welcome to Autodoc’s documentation! — Autodoc 0.1 documentation

### Navigation

- index
- Autodoc 0.1 documentation »

# Welcome to Autodoc’s documentation!

## What is Autodoc

Generate documentation from your unit-test.

This library is Python implementation of Autodoc. - Autodoc - Test::JsonAPI::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.

    AUTODOC=1 python -m unittest examples/test_unittest.py

If you use py.test as test runner.

    AUTODOC=1 py.test tests examples/test_pytest.py

If you use nose as test runner.

    AUTODOC=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() must 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

## Conventions

### Return WebTest 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 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

- Index
- Module Index
- Search Page

### Navigation

- index
- Autodoc 0.1 documentation »