如何基于rst书写openstack文档 （ by quqi99 )

  如何基于rst书写openstack文档 （ by quqi99 )

作者：张华  发表于：2013-01-24
版权声明：可以任意转载，转载时请务必以超链接形式标明文章原始出处和作者信息及本版权声明
( http://blog.csdn.net/quqi99 )

        关于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