如何编写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，生成后的工程目录形如：
      [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

         

          https://github.com/rackspace/wadl-tools