Metadata-Version: 1.1
Name: cornice-sphinx
Version: 0.3
Summary: Generate Sphinx documentation from a Cornice application
Home-page: https://github.com/Cornices/cornice.ext.sphinx
Author: Mozilla Services and contributors
Author-email: services-dev@mozilla.org
License: Apache License (2.0)
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**
        
          **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
        
Keywords: web services
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: Apache Software License
