cornice_sphinx

Cornice扩展用于生成Sphinx文档

在代码演变的同时维护文档是痛苦的。避免信息重复也是一个相当大的挑战。

Cornice通过提供一个Sphinx（《https://sphinx-doc.cn/》）指令，该指令扫描Web服务并使用在创建Service实例时提供的描述来构建文档，试图减少一些痛苦。

• 在创建Service实例时提供的描述来构建文档
• 涉及创建响应的所有函数的文档字符串：Web服务函数本身和验证器。

假设在编写代码的同时维护这些文档字符串更容易。

激活扩展

要激活Cornice指令，您必须在您的Sphinx项目中包含它：文件：conf.py文件：

import cornice

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

当然，如果您有其他扩展，这可能会变化。

服务指令

Cornice提供了一个名为cornice-autodoc的指令，您可以使用它将Web服务文档注入Sphinx。

该指令有以下选项

• modules：包含Cornice Web服务的Python模块的逗号分隔列表。Cornice将扫描它并查找服务。

• app：设置用于强制注册服务的应用程序的路径。

• services：服务的逗号分隔列表，如使用cornice Service指令时命名的。 可选

• service：如果您只有一个名称，则可以使用service而不是services。 可选

• ignore：要忽略的服务名称的逗号分隔列表。 可选

• docstring-replace：替换文档字符串中的某些单词。 可选

  module或app是必须的

您可以在函数、方法和验证器中使用信息字段（参见 信息字段列表 <https://sphinx-doc.cn/domains.html#info-field-lists>_）。

.. note:: 此指令曾经命名为 "services" 并已重命名为与Sphinx生态系统更一致的名字。

完整示例

假设您有一个名为 quote 的项目，其中有一个服务，您可以通过它 POST 和 GET 一个报价。

该服务确保报价以大写字母开头并以句号结尾 !

以下是 完整 的声明式应用程序：

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()

以下是 完整 的Sphinx文档示例：

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

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

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

以下是 完整 的强制应用程序：

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()

客户端调用：

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

以下是 完整 的Sphinx文档示例：

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

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

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

生成的文档是

.. image:: cornice.png