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_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.
Raw data
{
"_id": null,
"home_page": "http://github.com/heavenshell/py-autodoc",
"name": "autodoc",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Shinya Ohyanagi",
"author_email": "sohyanagi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/4e/c3/61f746096d2b6c161bd7f3bf8db1fe741b8805cbf0ac9369b4953c37de35/autodoc-0.5.0.tar.gz",
"platform": "any",
"description": "Autodoc\n=======\nGenerate documentation from your unit-test.\n\n.. image:: https://travis-ci.org/heavenshell/py-autodoc.png?branch=master\n\nThis library is Python implementation of Autodoc.\n\n- `Autodoc <https://github.com/r7kamura/autodoc>`_\n- `Test::JsonAPI::Autodoc <https://metacpan.org/pod/Test::JsonAPI::Autodoc>`_\n\nLinks\n-----\n\n- `Repository <https://github.com/heavenshell/py-autodoc>`_\n- `Documentation <http://autodoc.readthedocs.org/en/latest/>`_\n\n\nInstallation\n------------\n\n::\n\n $ virtualenv --distribute autodoc_sample\n $ source autodoc/bin/activate\n $ cd autodoc\n $ pip install autodoc\n\n\nUsage\n-----\nRun unittest with PYAUTODOC=1 to generate documents for your tests decorated with `@autodoc.generate`.\n\n::\n\n PYAUTODOC=1 python -m unittest examples/test_unittest.py\n\nIf you use py.test as test runner.\n\n::\n\n PYAUTODOC=1 py.test tests examples/test_pytest.py\n\nIf you use nose as test runner.\n\n::\n\n PYAUTODOC=1 nosetests tests examples/test_unittest.py\n\nExample for unittest\n--------------------\n::\n\n class TestUnittest(TestCase):\n def setUp(self):\n app = create_app\n self.client = TestApp(app)\n\n @classmethod\n @autodoc.generate('var/test_unittest.rst')\n def tearDownClass(cls):\n pass\n\n @autodoc.describe('GET /')\n def test_get(self):\n \"\"\" GET / \"\"\"\n res = self.client.get('/')\n self.assertEqual(res.status_code, 200)\n\n return res\n\n\n`@autodoc.describe()` describe test name.\n\nFor example `GET /` assigned to generated document.\n\n`@autodoc.generate(path_to_output)` will generate document.\n\n\nExample for py.test\n-------------------\n::\n\n @pytest.fixture\n def setup():\n setup = TestApp(create_app)\n\n return setup\n\n\n @autodoc.generate('var/test_pytest.md', template='templates/markdown.md')\n def teardown_module(module):\n pass\n\n\n @autodoc.describe('POST /')\n def test_post(setup):\n res = setup.post_json('/', params={'id': 1, 'message': 'foo'})\n assert res.status_code == 200\n\n return res\n\n\nExample for requests\n--------------------\n::\n\n import requests\n\n class TestUnittest(TestCase):\n def setUp(self):\n self.client = requests\n\n @classmethod\n @autodoc.generate('var/test_unittest.rst')\n def tearDownClass(cls):\n pass\n\n @autodoc.describe('POST /')\n def test_post(self):\n \"\"\" POST / \"\"\"\n params = {'id': 1, 'message': 'foo'}\n headers = {'content-type': 'application/json'}\n res = self.client.post('http://example.com/',\n data=params, headers=headers)\n self.assertEqual(res.status_code, 200)\n\n return res\n\n\nConventions\n-----------\n\nReturn WebTest or requests response in test method\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPy-Autodoc must return WebTest response.\n\n::\n\n @autodoc.describe('POST /')\n def test_post(setup):\n res = setup.post_json('/', params={'id': 1, 'message': 'foo'})\n assert res.status_code == 200\n\n return res # Must return WebTest or requests response.\n\n\n\nGenerate document point\n~~~~~~~~~~~~~~~~~~~~~~~\n\n`@autodoc.generate` will create document.\n\nIf you set `@autodoc.generate` to each test case, document will generate each file.\n\n::\n\n class TestUnittest(TestCase):\n def setUp(self):\n app = create_app\n self.client = TestApp(app)\n\n @autodoc.generate('var/indext_get.rst')\n @autodoc.describe('GET /')\n def test_get(self):\n \"\"\" GET / \"\"\"\n res = self.client.get('/')\n self.assertEqual(res.status_code, 200)\n\n return res\n\n @autodoc.generate('var/foo_get.rst')\n @autodoc.describe('GET /foo')\n def test_get(self):\n \"\"\" GET / \"\"\"\n res = self.client.get('/foo')\n self.assertEqual(res.status_code, 200)\n\n return res\n\nThis will generate `var/index_get.rst` and `var/foo_get.rst`.\n\nIf you want to generate all tests into single file,\ndecorate `@autodoc.generate` to `tearDownClass`, `teardown_module` fixture.\n\n\nConfiguration\n-------------\nYou can configure `@autodoc.generat(output, template=path_to_template)` to change template file.\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Autodoc Python implementation.",
"version": "0.5.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "8dc64fcb77a0a899ec765a636d0830ca",
"sha256": "c4387c5a0f1c09b055bb2e384542ee1e016542f313b2a33d904ca77f0460ded3"
},
"downloads": -1,
"filename": "autodoc-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "8dc64fcb77a0a899ec765a636d0830ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14178,
"upload_time": "2018-06-03T02:53:33",
"upload_time_iso_8601": "2018-06-03T02:53:33.661748Z",
"url": "https://files.pythonhosted.org/packages/4e/c3/61f746096d2b6c161bd7f3bf8db1fe741b8805cbf0ac9369b4953c37de35/autodoc-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2018-06-03 02:53:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "heavenshell",
"github_project": "py-autodoc",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"tox": true,
"lcname": "autodoc"
}
JSON
