https://github.com/heavenshell/py-autodoc

Autodoc Python implementation.
https://github.com/heavenshell/py-autodoc

Last synced: about 1 year ago
JSON representation

Autodoc Python implementation.

• Host: GitHub
• URL: https://github.com/heavenshell/py-autodoc
• Owner: heavenshell
• License: bsd-3-clause
• Created: 2014-01-25T02:45:47.000Z (over 12 years ago)
• Default Branch: master
• Last Pushed: 2023-05-23T02:03:41.000Z (about 3 years ago)
• Last Synced: 2024-06-19T13:45:58.725Z (about 2 years ago)
• Language: Python
• Homepage:
• Size: 75.2 KB
• Stars: 7
• Watchers: 3
• Forks: 3
• Open Issues: 5
• Metadata Files:
  • Readme: README.rst
  • Changelog: CHANGES.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
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 `_

- `Test::JsonAPI::Autodoc `_

Links

-----

- `Repository `_

- `Documentation `_

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.