Generate Documentation

Lovely PyRest provides a sphinx extension to generate service documentation. The generated documentation contains:

• Service Description
• HTTP-Method overview
• Accept Header
• Content-Type Header
• Schema

Include the extension

To include the extension add the following line to the config.py in your Spinx-Project:

extensions = ['lovely.pyrest.sphinx']

If you have other extensions use:

extensions.append('lovely.pyrest.sphinx')

If you don’t want to specify the module when using the sphinx directive add:

pyramid_conf = <path-to-app-conf>

Example

Assume you have a Service with a Schema:

from lovely.pyrest.rest import RestService, rpcmethod_route
from lovely.pyrest.validation import validate

# Create a schema to validate the body
schema = {
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        }
    }
}


@RestService('article')
class ArticleService(object):
    """ Create and read articles """

    @rpcmethod_route(request_method='POST',
                     content_type='application/json')
    def create(self, data):
        """ Update article """
        return {'created': '123'}

    @rpcmethod_route(request_method='GET',
                     accept='application/json')
    @validate(schema)
    def get(self, id):
        """ Returns the article """
        return {'title': 'the title'}


def includeme(config):
    config.add_route('article', '/article', static=True)

To automatically generate the documentation include the service directive in your rst file like in this:

Articles
========

Description
-----------

.. service:: testing.examples.sphinx

This is the generated documentation.

Directives

Lovely PyRest provides three directives to autogenerate the documentation.

Service Directive

The Service directive renders all services defined in a module. This modulde must be provided as argument:

.. service:: myapp.service

If the pyramid_conf option is set in the sphinx config file (conf.py) it’s possible to ommit the module:

.. service::

It’s also possible to specify base url of the service if you don’t want to render all services:

.. service::
    :services: article

Or:

.. service::
    myapp.service
    :services: article