关于openstack的文档,可参考:http://wiki.openstack.org/Documentation/HowTo
两类文档:
1) 程序员用的rest api文档用rst格式书写, 如http://docs.openstack.org/developer/nova/
2)其他一些如deployers, admins, and CLI and API users用Docbook书写,如http://github.com/openstack/openstack-manuals
本文要描述的是如何用rst格式写rest api文档:
eclipse有一个支持对rst所见即所得的插件,下载地址:http://sourceforge.net/projects/resteditor/files/eclipse/
一个名为test.rst的rst文档的例子如下,这个例子包括:
1)标题1
2)标题2
3)表格
4)列表
5)代码块
6)注释
具体怎么用直接见下面的代码吧,代码中有注释
..
Copyright 2013-2013
author, zhang hua, http://blog.csdn.net/quqi99
Title 1, use "====", how to write rst doc
=========================================
This is title, one rst example.
Title 2, use "----", one table example
--------------------------------------
This is table example.
==== ============================================ =======================
Verb URI Description
==== ============================================ =======================
GET clouds/{cloud_id}/networks Retrieve list of network extensions
==== ============================================ =======================
Title 3, Query Parameters
+++++++++++++++++++++++++
The following table shows the query parameters for this service.
=========== ================================= ========
Attribute Description Required
=========== ================================= ========
osNetworkId The id of OpenStack network. No
=========== ================================= ========
Code block need begin with ::
+++++++++++++++++++++++++++++
::
{
"name": "Zhang Hua",
"url": "http://blog.csdn.net/quqi99"
}
List need begin with *
++++++++++++++++++++++
The following attributes are used in the request body:
* ``name``
Human-readable name. Might not be unique. Optional.
* ``url``
url value.
如果想要将rst文件生成html或者其他什么格式的话,需要安装python的sphinx模块,安装方法:pip install sphinx
一个关于sphinx的文档参见:http://code.google.com/p/pymotwcn/wiki/SphinxprojectHowto
1) 安装sphinx后,运行命令“sphinx-quickstart”可生成一个doc project,生成后的工程目录形如:
[hua@zhanghua tmp]$ ls
_build conf.py index.rst make.bat Makefile output _static _templates
2) 可用 sphinx-build -b html . output 或者 make html命令生成html文档,生成的文档位于output目录
[hua@zhanghua tmp]$ ls output/
genindex.html index.html objects.inv search.html searchindex.js _sources _static
3) 将上面的rst文档例子test.rst作为链接添加到index.rst中来
Contents:
.. toctree::
:maxdepth: 2
doc/test.rst
4) 看看效果吧
如果定义了新的resource的话,还要考虑写WADL文件,WADL非常适合写REST的文档,
我们知道,WSDL, Web Services Description Language, 是一个基于SOAP的描述语言,SOAP协议是架在HTTP协议之上的,仅支持GET和POST,对于REST中有GET,POST,还有DELTE和 PUT,WSDL在这方面支持的不大好。虽然WSDL2.0也能支持像PUT这些动词了。
但WADL也是一种选择,Web Application Description Language, 通过github.com/rackspace/wadl-tools可以很方便地为REST API产生文档。
可以这样讲,如果说WSDL是用来描述SOAP类型的WEB服务的语言的话,WADL就是描述WEB服务API的语言,它允许你产生代码、测试和文档。
Openstack中用WADL生成的文档的样子长得什么样呢?参见:http://api.openstack.org/api-ref.html
关于在openstack中怎么用rst写文档,openstack社区还有一个模板,见:https://github.com/RackerWilliams/extension-doc-templates/tree/master/rst
模板的raw格式内容是:https://raw.github.com/RackerWilliams/extension-doc-templates/master/rst/extension_template.rst
下面看看如何通SoapUI ( http://sourceforge.net/projects/soapui/files/soapui-eclipse-plugin/4.0.1/ )为一个wsal生成文档,参考文档,http://www.soapui.org/REST-Testing/working-with-rest-services.html
openstack社区有一篇文章描述如何写wadl文件,http://wiki.openstack.org/Documentation/APISite/DocumentingWadls
这是一个写wadl文件的工具,可用java的javaws命令打开,http://docs.rackspace.com/oxygen/oxygenJWS/oxygen.jnlp
git clone git://github.com/openstack/api-site.git
相关推荐
云计算,虚拟化知识
- 安装完成后,可以查看`keystonerc_admin`和`keystonerc_demo`文件,它们包含了访问OpenStack API所需的认证信息。 5. **OpenStack网络配置**: - 手动配置: - 使用`ovs-vsctl`命令添加端口到Open vSwitch桥接...
- **OpenStack文档**:鼓励社区成员参与文档的编写和改进。 - **Python开发者文档**:为Python开发者提供资源和支持。 - **语言绑定和Python客户端**:介绍了与OpenStack交互的各种编程语言绑定。 - **OpenStack...
本文档中推荐使用CentOS 64位版本,因为该版本广泛支持OpenStack的各项功能,并且社区支持良好。 ##### 创建虚拟机步骤: 1. **选择操作系统**:选择Linux操作系统,推荐使用CentOS 64位。 2. **添加映像文件**:...
访问OpenStack官方网站(http://www.openstack.org/)和Swift的参考文档(http://swift.openstack.org/development_saio.html)获取最新的信息和更新。 **安装依赖包**: 安装Swift之前,你需要安装一系列的依赖...
文档还提及了各个项目的官方安装手册,对于任何有兴趣深入学习OpenStack的初学者而言,这份安装文档有着重要的指导意义。此外,文档也强调了在进行安装之前,用户需遵守Apache License, Version 2.0的版权声明,以...
### OpenStack核心概念与部署详解 #### OpenStack简介 OpenStack是一个开源的云计算管理平台项目,它提供了一系列的工具和服务来构建和管理云端计算资源。OpenStack的核心优势在于它的灵活性和扩展性,允许用户...
openstack高可用配置文档,openstack高可用配置文档,openstack高可用配置文档,openstack高可用配置文档,openstack高可用配置文档
### OpenStack 学习文档知识点解析 #### 一、OpenStack 概述 **OpenStack** 是一个开源的云计算管理平台项目,它提供了一个可扩展的 API 驱动型框架,用于部署和管理大规模计算、存储和服务资源。OpenStack 的核心...
OpenStack是一种开源的云计算平台,用于构建、部署和管理私有云和公共云服务。...这个“Openstack学习文档”压缩包很可能是包含这些关键知识点的教程、手册或案例研究,对初学者和进阶者都是宝贵的参考资料。
OpenStack架构设计指南是针对那些希望充分利用OpenStack云平台优势的用户而编写的。这份文档提供了详尽的规划、设计和架构建议,旨在确保用户在实施OpenStack时能充分考虑并满足他们的具体需求。OpenStack是一个开源...
OpenStack4j is an open source library that helps you manage an OpenStack deployment. It is a fluent based API giving you full control over the various OpenStack services.
2.1_什么是OpenStack(2017.5.30) 2.2_OpenStack之于虚拟化(2017.5.30) 2.3_OpenStack之于云计算(2017.5.30) 2.4_OpenStack发展历程(2017.5.30) 2.5_OpenStack的设计准则(2017.5.30) 2.6_OpenStack的架构(2017.5...
4. **OpenStack Python SDK**:开发者可以使用Python编写自动化脚本来创建和管理云环境中的资源。Python SDK封装了OpenStack API,使得用户可以通过调用Python对象来执行任务,无需直接调用REST接口。所有OpenStack...
云计算环境CentOS6.2操作系统下OpenStack完整安装手册
在详细设计文档中,OpenStack平台高可用性的构建和部署是核心议题。首先,文档提及了OpenStack环境架构,强调了针对计算存储一体的场景下,平台由两种类型的节点组成:一种是Controller-network-node,它运行包括...
- **日志文件分析**:解析OpenStack系统产生的日志文件,帮助诊断问题。 #### 四、社区支持与文档 - **官方文档**:提供了详细的OpenStack文档和指南。 - **ask.openstack.org**:一个问答社区,供用户提问和解答...