Skip to main content

Autodoc Python implementation.

Project description

Generate documentation from your unit-test.

https://travis-ci.org/heavenshell/py-autodoc.png?branch=master

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

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
autodoc-0.5.0.tar.gz (14.2 kB) Copy SHA256 hash SHA256 Source None Jun 3, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page