Metadata-Version: 2.0
Name: tz-okapi
Version: 0.2.9
Summary: Okapi is a simple tool to create documentation for your API and cover
Requires-Dist: colorama (>=0.3.3)
Requires-Dist: docopt (>=0.6.1)
Requires-Dist: docutils (>=0.12)
Requires-Dist: Jinja2 (>=2.7.3)
Requires-Dist: Pygments (>=2.0.2)
Requires-Dist: requests (>=2.7.0)
Requires-Dist: urllib3 (>=1.10.4)

it with tests. It is based on reStructuredText format and very easy to learn.
Home-page: https://github.com/Team-Zeus/okapi
Author: UNKNOWN
Author-email: UNKNOWN
License: UNKNOWN
Description: okapi
        =====
        
        .. image:: https://circleci.com/gh/Team-Zeus/okapi/tree/master.svg?style=svg&circle-token=71c675badd691f1e9e51bee3633b8fcf105497d6
          :target: https://circleci.com/gh/Team-Zeus/okapi/tree/master
        
        **To have API documentation OK.**
        
        Okapi is a simple tool to create **documentation for your API** and **cover
        it with tests**. It is based on *reStructuredText* format and very easy to learn.
        
        
        ----
        
        .. contents:: **Contents:**
        
        ----
        
        
        .. image:: https://c1.staticflickr.com/9/8050/8429119812_884f135860_b.jpg
          :alt: Okapi
          :width: 25%
          :align: right
        
        
        Requirements
        ------------
        
        - Python **3.4**
        
        For developing install requirements from ``requirements.txt``.
        
        .. code:: bash
        
            pip install -r requirements.txt
        
        
        Installation
        ------------
        
        .. code:: bash
        
            sudo pip3 install tz-okapi
        
        
        Install from sources:
        
        .. code:: bash
        
            python setup.py install
        
        
        Install from package:
        
        .. code:: bash
        
            pip install wheel
            pip install tz_okapi-*.whl
        
        
        On Windows you might add Python to paths::
        
          setx path "%path%;C:\Python34;C:\Python34\Scripts;"
        
        
        Usage
        -----
        
        ::
        
          okapi
        
          Usage:
              okapi [<in> -cdo <out> --url=<url> --config=<config> --headers=<headers> -v <verbosity> --prototype]
        
          Options:
              -c                      Enable persistent cache for responses.
              -d                      Allow debug mode.
              -o <out>                Output directory
              -v <verbosity>          Verbosity level [default: 2]
                                          0 - no output
                                          1 - summary
                                          2 - failed tests
                                          3 - all
        
              --url=<url>             URL against the requests are made
              --headers=<headers>     Custom headers sent to API, not visible in doc.
                                      (Comma separated).
              --config=<config>       Config file. [default: okapi.cfg]
              --prototype             Run in prototype mode (no requests are made).
        
          Example:
              okapi notebook.rst -o index.html --url=http://www.notebook.com/
        
        
        Example configuration file
        **************************
        
        .. code:: ini
        
          [base]
          file = notebook-api.rst
          output = docs/api
          url = http://www.mynotebook/
          cache = 1
          templates = docs/api/templates
          verbosity = 2
        
        
        
        Example
        -------
        
        .. code:: rst
        
          Notebook API documentation
          ==========================
        
          Notebook is a project to create and read notes.
        
          In every request, it should be sent this headers:
        
          .. code:: headers
        
            Accept-Type: application/json
            Accept-Language: en,fr
        
        
          Create new note
          ---------------
        
          To create new note use this POST method. Note can be created
          only with authenticated user.
        
          .. code:: request
        
            POST /api/note/create/
            Authentication: johnsmith:topsecretpass
        
            {
              "title": "My Note Title",
              "text": "Very long text..."
            }
        
            > status_code == 201
            > 'id' in json()
        
          If user is not successfully authenticated, status code ``401``
          is returned:
        
          .. code:: request
        
            POST /api/note/create/
        
            > status_code == 401
        
        
          Get note detail
          ---------------
        
          To get note detail, you have to provide its ``id``.
        
          For example:
        
          .. code:: request
        
            GET /api/note/{id:1}/
        
            > status_code == 200
            > 'title' in json()
            > 'text' in json()
        
        
          Get notes list
          --------------
        
          To get all notes use this request:
        
          .. code:: request
        
            GET /api/notes/
        
            > status_code == 200
        
          It is possible to filter by creation date:
        
          .. code:: request
        
            GET /api/notes/?date=2015-01-01
        
            > status_code == 200
        
        
        Not enough? Continue in reading...
        
        Motivation
        ----------
        
        We were long time looking for a tool to create documentation for APIs of
        our projects. We tried `Apiary <https://apiary.io/>`_, we tried
        `Swagger <http://swagger.io/>`_ and more and more tools, but none has satisfied us.
        
        We needed tool, which would be:
        
        - **DRY.** We are lazy to repeat our selves. Repeating is a way do many mistakes.
        - **KISS.** Every member of team should be able to edit it without knowing some
          special syntax or rules. So super stupid simple.
        - **Changeable.** It means, that man wouldn't edit documentation for hours after
          every small change in API.
        - **Readable** in raw format.
        - Usable for **non-REST APIs** (but for REST API, too, of course).
        - **Testable.** Documentation not covered with tests is hard to maintance.
        
        
        Specification
        -------------
        
        headers
        *******
        
        Block used at the beginning of document to set common headers sent with
        request and disabled headers hidden from response. It should be used only
        once.
        
        ::
        
          .. code:: headers
        
            [HEADER_NAME: HEADER_VALUE]
            ...
        
        
        request
        *******
        
        Block to describe API request. It has four parts:
        
        1. method and url (required)
        2. headers (optional)
        3. payload (optional)
        4. tests (recommended)
        
        ::
        
            .. code:: request
        
                (GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|TRACE|CONNECT) (URL) [HTTP_VERSION]
                [HEADER_NAME: HEADER_VALUE]
                ...
        
                [{ ... json payload ... }]
        
                [
                > tests
                > ..
                ]
        
        
        url
        ****
        
        URL cannot contain any space. Use encoded strings (``%20`` or ``+``).
        
        URLs can be with described params:
        
        ::
        
          {NAME:VALUE}
        
        eg.::
        
          /api/note/{typeId:1}/{noteId:3}/
        
        
        
        Change log
        ==========
        
        Release 0.2.9 (2015/09/22)
        --------------------------
        
        - Fix UnicodeEncodeError during saving output.
        
        Release 0.2.8 (2015/08/05)
        --------------------------
        
        - #32 - Add MIT license
        - #33 - Fix bad interpreter error.
        
        Release 0.2.7 (2015/08/04)
        --------------------------
        
        - #12 - Fix path with using of include directive.
        
        Release 0.2.6 (2015/08/04)
        --------------------------
        
        - #30 - Added ``--prototype`` option to run in prototype mode. Prototype mode
          doesn't execute any request, responses are faked.
        
        - #31 - Added automatically generated sidebar TOC to default template.
        
        Release 0.2.5 (2015/07/27)
        --------------------------
        
        - #27 - Added *click on scroll* functionality. Request and response are not
          scrollable by default, user has to click on them.
        
        - #26 - Fixed default template to show response status code even if response
          is empty.
        
Keywords: api,rest,restructuredtext,rst
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Documentation
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Utilities
