支持openstack中api引用站点的sphinx扩展
os-api-ref的Python项目详细描述
操作系统API参考
sphinx扩展以支持openstack中的api引用站点
这个项目是一个狮身人面像节的集合，有助于建筑 RST中OpenStack项目的API引用站点。RST很棒 对于非结构化英语，但显示半结构化（和 重复）表格中的数据不是它的强项。这提供了工具 插入描述请求和响应的半结构化数据 参数和状态或错误消息，并将它们转换成漂亮的表。
该项目还包括一组样式（和javascript），即 应在狮身人面像主题基础上分层。这一增加 为rest方法和 用于展开/折叠所有节的javascript控件。
功能
- sphinx节rest_method描述rest的方法和资源 API调用。让作者写得简单，也给读者一个干净的方法 扫描所有方法，然后单击按钮以获取有关方法的详细信息。
- Sphinx节rest_parameters用于将半结构化数据插入 描述用户可以随请求发送的参数的rst文件。这个 节指向结构化的yaml文件parameters.yaml。
- Sphinx节rest_status_code用于插入指向错误或状态的指针 服务返回的代码指向结构化的yaml文件， http_codes.yaml
待办事项
我们在这件事上应该做的事情的清单，没有特别的顺序 项目。如果你想为这些做贡献，请展示 在irc上的#openstack-dev中向上请求sdague或mugsie 讨论或向openstack-discuss@lists.openstack.org列表发送电子邮件 主题行中有[api]
- 通过更多示例和最佳实践增强文档功能
- 测试代码
- max_microversion参数支持-以便我们自动 已删除的标记参数
- 制作一个微版本选择器，这样您就可以得到一个版本的api ref 隐藏所选版本之外的所有微版本元素 （这将是一个有点复杂的javascript），正在进行中。
潜在的想法
这些都不是什么好做的事，只是一些可能 要有用。
- .. literalinclude适合包含API示例文件， 但是我们是否应该有更多的标记，包括完整的REST /URL 也。
狮身人面像节
rest_方法：输入rest方法，例如get、put、post、delete， 后跟调用的资源（不包括终结点）。为了 示例：
.. rest_method:: PUT /v2/images/{image_id}/file
rest_参数：输入对parameters.yaml文件的引用，然后 指示要记录的参数例如：
.. rest_parameters:: images-parameters.yaml - Content-type: Content-Type-data - image_id: image_id-in-path
其中images-parameters.yaml文件包含名为 Content-type和image_id以及每个的说明。
rest\u状态代码：输入对http-status.yaml文件的引用，然后 指出要记录的错误或状态代码。您还可以添加 指向每个代码更精确描述的指针。例如：
.. rest_status_code:: success http-codes.yaml - 204 .. rest_status_code:: error http-codes.yaml - 400: informal - 401 - 403 - 404 - 409 - 410: image-data-410 - 413: image-data-413 - 415: image-data-415 - 500: informal - 503: image-data-503
欢迎加入QQ群-->： 979659372
