设为首页 收藏本站
查看: 2610|回复: 0

[经验分享] 如何编写OpenStack文档rst文件

[复制链接]

尚未签到

发表于 2016-1-9 07:32:13 | 显示全部楼层 |阅读模式
  关于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) 看看效果吧
DSC0000.png
  
  如果定义了新的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、欢迎大家加入本站运维交流群:群②:261659950 群⑤:202807635 群⑦870801961 群⑧679858003
2、本站所有主题由该帖子作者发表,该帖子作者与运维网享有帖子相关版权
3、所有作品的著作权均归原作者享有,请您和我们一样尊重他人的著作权等合法权益。如果您对作品感到满意,请购买正版
4、禁止制作、复制、发布和传播具有反动、淫秽、色情、暴力、凶杀等内容的信息,一经发现立即删除。若您因此触犯法律,一切后果自负,我们对此不承担任何责任
5、所有资源均系网友上传或者通过网络收集,我们仅提供一个展示、介绍、观摩学习的平台,我们不对其内容的准确性、可靠性、正当性、安全性、合法性等负责,亦不承担任何法律责任
6、所有作品仅供您个人学习、研究或欣赏,不得用于商业或者其他用途,否则,一切后果均由您自己承担,我们对此不承担任何法律责任
7、如涉及侵犯版权等问题,请您及时通知我们,我们将立即采取措施予以解决
8、联系人Email:admin@iyunv.com 网址:www.yunweiku.com

所有资源均系网友上传或者通过网络收集,我们仅提供一个展示、介绍、观摩学习的平台,我们不对其承担任何法律责任,如涉及侵犯版权等问题,请您及时通知我们,我们将立即处理,联系人Email:kefu@iyunv.com,QQ:1061981298 本贴地址:https://www.yunweiku.com/thread-162028-1-1.html 上篇帖子: openstack安装笔记 环境(零) 下篇帖子: OpenStack和CloudStack对比研究报告
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

扫码加入运维网微信交流群X

扫码加入运维网微信交流群

扫描二维码加入运维网微信交流群,最新一手资源尽在官方微信交流群!快快加入我们吧...

扫描微信二维码查看详情

客服E-mail:kefu@iyunv.com 客服QQ:1061981298


QQ群⑦:运维网交流群⑦ QQ群⑧:运维网交流群⑧ k8s群:运维网kubernetes交流群


提醒:禁止发布任何违反国家法律、法规的言论与图片等内容;本站内容均来自个人观点与网络等信息,非本站认同之观点.


本站大部分资源是网友从网上搜集分享而来,其版权均归原作者及其网站所有,我们尊重他人的合法权益,如有内容侵犯您的合法权益,请及时与我们联系进行核实删除!



合作伙伴: 青云cloud

快速回复 返回顶部 返回列表