Package: cornice-sphinx
cornice_sphinxCornice extension to generate Sphinx docMaintaining 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 createdthe 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 extensionTo activate Cornice's directive, you must include it in your
Sphinx project :file:conf.pyfile::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 directiveCornice provides acornice-autodocdirective 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 corniceServicedirective.optionalservice: if you have only one name, then you can useservicerather
thanservices.optionalignore: a comma separated list of services names to ignore.optionaldocstring-replace: replace certain words in docstring.optionalmoduleorapparemandatoryYou can use info fields (seeInfo 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 exampleLet's say you have aquoteproject with a single service where you
canPOSTandGETa quote.The service makes sure the quote starts with a majuscule and ends with
a dot !Here's thefulldeclarative 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 thefullSphinx 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: quoteHere's thefullimperative 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 thefullSphinx 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: quoteThe resulting doc is:.. image:: cornice.png