如何编写OpenStack文档rst文件
关于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，生成后的工程目录形如：
$ ls
_build conf.py index.rst make.bat Makefile output _static _templates
2) 可用 sphinx-build -b html . output 或者 make html命令生成html文档，生成的文档位于output目录
$ 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
https://github.com/rackspace/wadl-tools
页:
[1]