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.

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

Project details


Download files

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

Source Distribution

autodoc-0.1.tar.gz (92.5 kB view details)

Uploaded Source

File details

Details for the file autodoc-0.1.tar.gz.

File metadata

  • Download URL: autodoc-0.1.tar.gz
  • Upload date:
  • Size: 92.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for autodoc-0.1.tar.gz
Algorithm Hash digest
SHA256 ddcab27ac0aa85efcfda7cb56cb61d9c8f418d704c2993a9a813fdb96c6b2154
MD5 6e14f4091412563ed1a1ad25a98fc1d8
BLAKE2b-256 d4199309b616ae2be8e963538435aba0f952933ad69ecf33bbb277fb18451866

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page