`
mars914
  • 浏览: 432503 次
  • 性别: Icon_minigender_1
  • 来自: 北京
社区版块
存档分类
最新评论

如何编写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

分享到:
评论

相关推荐

    openstack文档.zip

    云计算,虚拟化知识

    openstack文档

    - 安装完成后,可以查看`keystonerc_admin`和`keystonerc_demo`文件,它们包含了访问OpenStack API所需的认证信息。 5. **OpenStack网络配置**: - 手动配置: - 使用`ovs-vsctl`命令添加端口到Open vSwitch桥接...

    OpenStack官方文档列表[中文版]

    - **OpenStack文档**:鼓励社区成员参与文档的编写和改进。 - **Python开发者文档**:为Python开发者提供资源和支持。 - **语言绑定和Python客户端**:介绍了与OpenStack交互的各种编程语言绑定。 - **OpenStack...

    openstack安装文档

    本文档中推荐使用CentOS 64位版本,因为该版本广泛支持OpenStack的各项功能,并且社区支持良好。 ##### 创建虚拟机步骤: 1. **选择操作系统**:选择Linux操作系统,推荐使用CentOS 64位。 2. **添加映像文件**:...

    OpenStack swift 安装文档

    访问OpenStack官方网站(http://www.openstack.org/)和Swift的参考文档(http://swift.openstack.org/development_saio.html)获取最新的信息和更新。 **安装依赖包**: 安装Swift之前,你需要安装一系列的依赖...

    openstack kilo 中文安装文档

    文档还提及了各个项目的官方安装手册,对于任何有兴趣深入学习OpenStack的初学者而言,这份安装文档有着重要的指导意义。此外,文档也强调了在进行安装之前,用户需遵守Apache License, Version 2.0的版权声明,以...

    openstack学习文档

    ### OpenStack核心概念与部署详解 #### OpenStack简介 OpenStack是一个开源的云计算管理平台项目,它提供了一系列的工具和服务来构建和管理云端计算资源。OpenStack的核心优势在于它的灵活性和扩展性,允许用户...

    openstack高可用配置文档

    openstack高可用配置文档,openstack高可用配置文档,openstack高可用配置文档,openstack高可用配置文档,openstack高可用配置文档

    openStack学习文档

    ### OpenStack 学习文档知识点解析 #### 一、OpenStack 概述 **OpenStack** 是一个开源的云计算管理平台项目,它提供了一个可扩展的 API 驱动型框架,用于部署和管理大规模计算、存储和服务资源。OpenStack 的核心...

    Openstack学习文档

    OpenStack是一种开源的云计算平台,用于构建、部署和管理私有云和公共云服务。...这个“Openstack学习文档”压缩包很可能是包含这些关键知识点的教程、手册或案例研究,对初学者和进阶者都是宝贵的参考资料。

    OpenStack-原文.pdf

    OpenStack架构设计指南是针对那些希望充分利用OpenStack云平台优势的用户而编写的。这份文档提供了详尽的规划、设计和架构建议,旨在确保用户在实施OpenStack时能充分考虑并满足他们的具体需求。OpenStack是一个开源...

    OpenStack4j 文档

    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.

    华为基于OpenStack的华为FusionSphere解决方案培训.rar

    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...

    OpenStack API文档

    4. **OpenStack Python SDK**:开发者可以使用Python编写自动化脚本来创建和管理云环境中的资源。Python SDK封装了OpenStack API,使得用户可以通过调用Python对象来执行任务,无需直接调用REST接口。所有OpenStack...

    CentOS6.2 OpenStack完整文档

    云计算环境CentOS6.2操作系统下OpenStack完整安装手册

    OpenStack+HA高可用详细设计文档.pdf

    在详细设计文档中,OpenStack平台高可用性的构建和部署是核心议题。首先,文档提及了OpenStack环境架构,强调了针对计算存储一体的场景下,平台由两种类型的节点组成:一种是Controller-network-node,它运行包括...

    OpenStack 管理员参考文档user-guide-admin

    - **日志文件分析**:解析OpenStack系统产生的日志文件,帮助诊断问题。 #### 四、社区支持与文档 - **官方文档**:提供了详细的OpenStack文档和指南。 - **ask.openstack.org**:一个问答社区,供用户提问和解答...

Global site tag (gtag.js) - Google Analytics