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
Raw data
{
"_id": null,
"home_page": "https://github.com/Cornices/cornice.ext.sphinx",
"name": "cornice-sphinx",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "web services",
"author": "Mozilla Services and contributors",
"author_email": "services-dev@mozilla.org",
"download_url": "https://files.pythonhosted.org/packages/9a/ff/a95583cc386558fc268800774b858d707ea6743c8dee810485bdf7584b11/cornice_sphinx-0.4.tar.gz",
"platform": null,
"description": "cornice_sphinx\n==============\n\n*Cornice extension to generate Sphinx doc*\n\nMaintaining documentation while the code is evolving is painful.\nAvoiding information duplication is also quite a challenge.\n\nCornice tries to reduce a bit the pain by providing a Sphinx\n(http://sphinx.pocoo.org/) directive that scans the web\nservices and build the documentation using:\n\n- the description provided when a Service instance is created\n- the docstrings of all functions involved in creating the response:\n the web services function itself and the validators.\n\nThe assumption made is that maintaining those docstrings while\nworking on the code is easier.\n\n\nActivate the extension\n----------------------\n\nTo activate Cornice's directive, you must include it in your\nSphinx project :file:`conf.py` file::\n\n import cornice\n\n sys.path.insert(0, os.path.abspath(cornice.__file__))\n extensions = ['cornice_sphinx']\n\nOf course this may vary if you have other extensions.\n\n\nThe service directive\n---------------------\n\nCornice provides a **cornice-autodoc** directive you can use to\ninject the Web Services documentation into Sphinx.\n\nThe directive has the following options:\n\n- **modules**: a comma-separated list of the python modules that contain\n Cornice Web services. Cornice will scan it and look for the services.\n- **app**: set the path to you app needed for imperative registering services.\n- **services**: a comma-separated list of services, as you named them when\n using the cornice `Service` directive. **optional**\n- **service**: if you have only one name, then you can use `service` rather\n than `services`. **optional**\n- **ignore**: a comma separated list of services names to ignore. **optional**\n- **docstring-replace**: replace certain words in docstring. **optional**\n\n **module** or **app** are **mandatory**\n\nYou can use info fields (see\n`Info field lists <http://sphinx.pocoo.org/domains.html#info-field-lists>`_)\nin your functions, methods and validators.\n\n.. note::\n This directive used to be named \"services\" and had been renamed for\n something more consistant with the Sphinx ecosystem.\n\nFull example\n------------\n\nLet's say you have a **quote** project with a single service where you\ncan **POST** and **GET** a quote.\n\nThe service makes sure the quote starts with a majuscule and ends with\na dot !\n\nHere's the **full** declarative app::\n\n from cornice import Service\n from pyramid.config import Configurator\n import string\n\n desc = \"\"\"\\\n Service that maintains a quote.\n \"\"\"\n\n quote = Service(name='quote', path='/quote', description=desc)\n\n\n def check_quote(request):\n \"\"\"Makes sure the quote starts with a majuscule and ends with a dot\"\"\"\n quote = request.body\n if quote[0] not in string.ascii_uppercase:\n request.errors.add('body', 'quote', 'Does not start with a majuscule')\n\n if quote[-1] not in ('.', '?', '!'):\n request.errors.add('body', 'quote', 'Does not end properly')\n\n if len(request.errors) == 0:\n request.validated['quote'] = quote\n\n\n _quote = {}\n _quote['default'] = \"Not set, yet !\"\n\n\n @quote.get()\n def get_quote(request):\n \"\"\"Returns the quote\"\"\"\n return _quote['default']\n\n\n @quote.post(validators=check_quote)\n def post_quote(request):\n \"\"\"Update the quote\"\"\"\n _quote['default'] = request.validated['quote']\n\n\n def main(global_config, **settings):\n config = Configurator(settings={})\n config.include(\"cornice\")\n config.scan(\"coolapp\")\n return config.make_wsgi_app()\n\n if __name__ == '__main__':\n from wsgiref.simple_server import make_server\n app = main({})\n httpd = make_server('', 6543, app)\n print(\"Listening on port 6543....\")\n httpd.serve_forever()\n\n\nAnd here's the **full** Sphinx doc example::\n\n Welcome to coolapp's documentation!\n ===================================\n\n My **Cool** app provides a way to send cool quotes to the server !\n\n .. cornice-autodoc::\n :modules: coolapp\n :service: quote\n\nHere's the **full** imperative app::\n\n from cornice import Service\n from pyramid.config import Configurator\n import string\n\n\n def check_quote(request):\n \"\"\"Makes sure the quote starts with a majuscule and ends with a dot\"\"\"\n quote = request.body\n if quote[0] not in string.ascii_uppercase:\n request.errors.add('body', 'quote', 'Does not start with a majuscule')\n\n if quote[-1] not in ('.', '?', '!'):\n request.errors.add('body', 'quote', 'Does not end properly')\n\n if len(request.errors) == 0:\n request.validated['quote'] = quote\n\n\n _quote = {}\n _quote['default'] = \"Not set, yet !\"\n\n\n def get_quote(request):\n \"\"\"Returns the quote\"\"\"\n return _quote['default']\n\n\n def post_quote(request):\n \"\"\"Update the quote\"\"\"\n _quote['default'] = request.validated['quote']\n\n\n def main(global_config, **settings):\n config = Configurator(settings={})\n config.include(\"cornice\")\n desc = \"Service that maintains a quote.\"\n quote = Service(name='quote', path='/quote', description=desc)\n quote.add_view(\"GET\", get_quote)\n quote.add_view(\"POST\", post_quote, validators=check_quote)\n config.add_cornice_service(quote)\n return config.make_wsgi_app()\n\n if __name__ == '__main__':\n from wsgiref.simple_server import make_server\n app = main({})\n httpd = make_server('', 6543, app)\n print(\"Listening on port 6543....\")\n httpd.serve_forever()\n\nClient calls::\n\n $ curl -X POST http://localhost:6543/quote -d Hansolohat.\n null\n $ curl -X GET http://localhost:6543/quote\n \"Hansolohat.\"\n\nAnd here's the **full** Sphinx doc example::\n\n Welcome to coolapp's documentation!\n ===================================\n\n My **Cool** app provides a way to send cool quotes to the server !\n\n .. cornice-autodoc::\n :app: coolapp\n :service: quote\n\n\nThe resulting doc is:\n\n.. image:: cornice.png\n",
"bugtrack_url": null,
"license": "Apache License (2.0)",
"summary": "Generate Sphinx documentation from a Cornice application",
"version": "0.4",
"project_urls": {
"Homepage": "https://github.com/Cornices/cornice.ext.sphinx"
},
"split_keywords": [
"web",
"services"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a55b36bf401bba46480c825ad26c53325bd963ab5be8abb35ea5e3dba38b7351",
"md5": "9f04f5c2b57b8a5af23c826f9cf86d89",
"sha256": "97ce2e23406a035ab0941e3345fdb81b120728a70fb994566968d7e5759df1e0"
},
"downloads": -1,
"filename": "cornice_sphinx-0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f04f5c2b57b8a5af23c826f9cf86d89",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11070,
"upload_time": "2023-10-05T17:52:44",
"upload_time_iso_8601": "2023-10-05T17:52:44.845442Z",
"url": "https://files.pythonhosted.org/packages/a5/5b/36bf401bba46480c825ad26c53325bd963ab5be8abb35ea5e3dba38b7351/cornice_sphinx-0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9affa95583cc386558fc268800774b858d707ea6743c8dee810485bdf7584b11",
"md5": "01782ec2b50ab75e8787bfd7ef23d152",
"sha256": "27dfb3861fb5bdb92fbd476f7bde87f6fb16903cf1d61eee7f492853f1fbf5fc"
},
"downloads": -1,
"filename": "cornice_sphinx-0.4.tar.gz",
"has_sig": false,
"md5_digest": "01782ec2b50ab75e8787bfd7ef23d152",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11064,
"upload_time": "2023-10-05T17:52:46",
"upload_time_iso_8601": "2023-10-05T17:52:46.875388Z",
"url": "https://files.pythonhosted.org/packages/9a/ff/a95583cc386558fc268800774b858d707ea6743c8dee810485bdf7584b11/cornice_sphinx-0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-05 17:52:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Cornices",
"github_project": "cornice.ext.sphinx",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "cornice-sphinx"
}
JSON
