Skip to main content

Generate Sphinx documentation from a Cornice application

Project description

cornice_sphinx

Cornice extension to generate Sphinx doc

Maintaining documentation while the code is evolving is painful. Avoiding information duplication is also quite a challenge.

Cornice tries to reduce a bit the pain by providing a Sphinx (http://sphinx.pocoo.org/) directive that scans the web services and build the documentation using:

  • the description provided when a Service instance is created
  • the docstrings of all functions involved in creating the response: the web services function itself and the validators.

The assumption made is that maintaining those docstrings while working on the code is easier.

Activate the extension

To activate Cornice's directive, you must include it in your Sphinx project :file:conf.py file::

import cornice

sys.path.insert(0, os.path.abspath(cornice.__file__))
extensions = ['cornice_sphinx']

Of course this may vary if you have other extensions.

The service directive

Cornice provides a cornice-autodoc directive you can use to inject the Web Services documentation into Sphinx.

The directive has the following options:

  • modules: a comma-separated list of the python modules that contain Cornice Web services. Cornice will scan it and look for the services.

  • app: set the path to you app needed for imperative registering services.

  • services: a comma-separated list of services, as you named them when using the cornice Service directive. optional

  • service: if you have only one name, then you can use service rather than services. optional

  • ignore: a comma separated list of services names to ignore. optional

  • docstring-replace: replace certain words in docstring. optional

    module or app are mandatory

You can use info fields (see Info field lists <http://sphinx.pocoo.org/domains.html#info-field-lists>_) in your functions, methods and validators.

.. note:: This directive used to be named "services" and had been renamed for something more consistant with the Sphinx ecosystem.

Full example

Let's say you have a quote project with a single service where you can POST and GET a quote.

The service makes sure the quote starts with a majuscule and ends with a dot !

Here's the full declarative app::

from cornice import Service
from pyramid.config import Configurator
import string

desc = """\
Service that maintains a quote.
"""

quote = Service(name='quote', path='/quote', description=desc)


def check_quote(request):
    """Makes sure the quote starts with a majuscule and ends with a dot"""
    quote = request.body
    if quote[0] not in string.ascii_uppercase:
        request.errors.add('body', 'quote', 'Does not start with a majuscule')

    if quote[-1] not in ('.', '?', '!'):
        request.errors.add('body', 'quote', 'Does not end properly')

    if len(request.errors) == 0:
        request.validated['quote'] = quote


_quote = {}
_quote['default'] = "Not set, yet !"


@quote.get()
def get_quote(request):
    """Returns the quote"""
    return _quote['default']


@quote.post(validators=check_quote)
def post_quote(request):
    """Update the quote"""
    _quote['default'] = request.validated['quote']


def main(global_config, **settings):
    config = Configurator(settings={})
    config.include("cornice")
    config.scan("coolapp")
    return config.make_wsgi_app()

if __name__ == '__main__':
    from wsgiref.simple_server import make_server
    app = main({})
    httpd = make_server('', 6543, app)
    print("Listening on port 6543....")
    httpd.serve_forever()

And here's the full Sphinx doc example::

Welcome to coolapp's documentation!
===================================

My **Cool** app provides a way to send cool quotes to the server !

.. cornice-autodoc::
   :modules: coolapp
   :service: quote

Here's the full imperative app::

from cornice import Service
from pyramid.config import Configurator
import string


def check_quote(request):
    """Makes sure the quote starts with a majuscule and ends with a dot"""
    quote = request.body
    if quote[0] not in string.ascii_uppercase:
        request.errors.add('body', 'quote', 'Does not start with a majuscule')

    if quote[-1] not in ('.', '?', '!'):
        request.errors.add('body', 'quote', 'Does not end properly')

    if len(request.errors) == 0:
        request.validated['quote'] = quote


_quote = {}
_quote['default'] = "Not set, yet !"


def get_quote(request):
    """Returns the quote"""
    return _quote['default']


def post_quote(request):
    """Update the quote"""
    _quote['default'] = request.validated['quote']


def main(global_config, **settings):
    config = Configurator(settings={})
    config.include("cornice")
    desc = "Service that maintains a quote."
    quote = Service(name='quote', path='/quote', description=desc)
    quote.add_view("GET", get_quote)
    quote.add_view("POST", post_quote, validators=check_quote)
    config.add_cornice_service(quote)
    return config.make_wsgi_app()

if __name__ == '__main__':
    from wsgiref.simple_server import make_server
    app = main({})
    httpd = make_server('', 6543, app)
    print("Listening on port 6543....")
    httpd.serve_forever()

Client calls::

$ curl -X POST http://localhost:6543/quote -d Hansolohat.
null
$ curl -X GET http://localhost:6543/quote
"Hansolohat."

And here's the full Sphinx doc example::

Welcome to coolapp's documentation!
===================================

My **Cool** app provides a way to send cool quotes to the server !

.. cornice-autodoc::
   :app: coolapp
   :service: quote

The resulting doc is:

.. image:: cornice.png

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cornice_sphinx-0.4.tar.gz (11.1 kB view details)

Uploaded Source

Built Distribution

cornice_sphinx-0.4-py3-none-any.whl (11.1 kB view details)

Uploaded Python 3

File details

Details for the file cornice_sphinx-0.4.tar.gz.

File metadata

  • Download URL: cornice_sphinx-0.4.tar.gz
  • Upload date:
  • Size: 11.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for cornice_sphinx-0.4.tar.gz
Algorithm Hash digest
SHA256 27dfb3861fb5bdb92fbd476f7bde87f6fb16903cf1d61eee7f492853f1fbf5fc
MD5 01782ec2b50ab75e8787bfd7ef23d152
BLAKE2b-256 9affa95583cc386558fc268800774b858d707ea6743c8dee810485bdf7584b11

See more details on using hashes here.

File details

Details for the file cornice_sphinx-0.4-py3-none-any.whl.

File metadata

  • Download URL: cornice_sphinx-0.4-py3-none-any.whl
  • Upload date:
  • Size: 11.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for cornice_sphinx-0.4-py3-none-any.whl
Algorithm Hash digest
SHA256 97ce2e23406a035ab0941e3345fdb81b120728a70fb994566968d7e5759df1e0
MD5 9f04f5c2b57b8a5af23c826f9cf86d89
BLAKE2b-256 a55b36bf401bba46480c825ad26c53325bd963ab5be8abb35ea5e3dba38b7351

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page