This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Autodoc Python implementation.

Project Description

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

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_get(self):
    """ GET / """
    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.

Release History

Release History

This version
History Node

0.3

History Node

0.2

History Node

0.1

Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
autodoc-0.3.tar.gz (93.6 kB) Copy SHA256 Checksum SHA256 Source Aug 9, 2014

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting