Skip to main content
Help us improve Python packaging – donate today!

Autodoc Python implementation.

Project Description

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

This version
History Node

0.3

History Node

0.2

History Node

0.1

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.3.tar.gz (93.6 kB) Copy SHA256 hash SHA256 Source None Aug 9, 2014

Supported by

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