Add API doc content (1)

This patch adds some sample API contents for versions and profile type
resources. A new tox environment is added for publishing pipeline.

Change-Id: I1e9d58a7d80633971935b7e0f5d983bb81d99a73

api-ref/source/index.rst

@@ -0,0 +1,8 @@
+:tocdepth: 2
+
+==============
+Clustering API
+==============
+
+.. include:: versions.inc
+.. include:: profile_types.inc

api-ref/source/parameters.yaml

@@ -0,0 +1,114 @@
+microversion:
+  type: string
+  in: header
+  optional: True
+  description: |
+    API microversion request. It takes the form of
+    ``openstack-api-version: clustering 1.0``, where ``1.0`` is the requested
+    API version.
+
+profile_type:
+  type: object
+  in: body
+  description: |
+    A structured description of a profile type.
+
+profile_type_name:
+  type: string
+  in: profile_type
+  description: |
+    The name of the profile type.
+
+profile_type_schema:
+  type: object
+  in: profile_type
+  description: |
+    The schema of a profile type. The schema of a profile type varies
+    a lot based on the specific type implementation. All profile types
+    share the ``context`` property which is a dictionary for customizing
+    the request context to authenticate with a backend service. A common
+    usage of this property is to set the ``region_name`` in the dictionary
+    so that a node can be created in the specified region. All other
+    properties are defined by a particular profile type implementation.
+
+profile_type_url:
+  type: string
+  in: URL
+  description: |
+    The name of a profile type.
+
+profile_types:
+  type: list
+  in: body
+  description: |
+    A list of profile_type objects.
+
+request_id:
+  type: UUID
+  in: header
+  description: |
+    A unique ID for tracking service request. The request ID associated
+    with the request by default appears in the service logs.
+
+version:
+  type: object
+  in: body
+  description: |
+    The details about a major API version.
+
+version_id:
+  type: string
+  in: version
+  description: |
+    The string representation of an API version number, e.g. ``1.0``.
+
+version_links:
+  type: list
+  in: version
+  description: |
+    A list of relative URLs to different version objects.
+
+version_max_version:
+  type: string
+  in: version
+  description: |
+    The string representation of the maximum microversion supported.
+
+version_media_types:
+  type: list
+  in: version
+  description: |
+    A list of content-type based media type request supported.
+
+version_min_version:
+  type: string
+  in: version
+  description: |
+    The string representation of the minimum microversion supported.
+
+version_status:
+  type: string
+  in: version
+  description: |
+    A string indicating the supporting status of the version.
+
+version_updated:
+  type: string
+  in: version
+  description: |
+    The date and time when the version was last updated. The data and time
+    stamp format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
+
+      ``2016-01-18T00:00:00Z``
+
+version_url:
+  type: string
+  in: URL
+  description: |
+    A string indicating the major version of Clustering API.
+
+versions:
+  type: list
+  in: body
+  description: |
+    A list of supported major API versions.

api-ref/source/profile_types.inc

@@ -0,0 +1,73 @@
+=============================
+Profile Types (profile-types)
+=============================
+
+Lists all profile types and shows details for a profile type.
+
+List profile types
+==================
+
+.. rest_method::  GET /v1/profile-types
+
+Lists supported profile types.
+
+Normal response codes: 200
+Error response codes: unauthorized (401), forbidden (403),
+serviceUnvailable (503)
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - microversion: microversion
+
+Response Example
+----------------
+
+.. literalinclude:: samples/profile-types-list-response.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - profile_types: profile_types
+
+
+Show profile type details
+=========================
+
+.. rest_method::  GET /v1/profile-types/{profile_type}
+
+Shows details for a profile type.
+
+
+Normal response codes: 200
+Error response codes: unauthorized (401), forbidden (403),
+notFound (404), serviceUavailable (503)
+
+
+Request Parameters
+------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - microversion: microversion
+  - profile_type: profile_type_url
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - profile_type: profile_type
+  - name: profile_type_name
+  - schema: profile_type_schema
+
+Response Example
+----------------
+
+.. literalinclude:: samples/profile-type-show-response.json
+   :language: javascript

api-ref/source/samples/profile-type-show-response.json

@@ -0,0 +1,61 @@
+{
+    "profile_type": {
+        "name": "os.heat.stack-1.0",
+        "schema": {
+            "context": {
+                "default": {},
+                "description": "A dictionary for specifying the customized context for stack operations",
+                "readonly": false,
+                "required": false,
+                "type": "Map",
+                "updatable": false
+            },
+            "disable_rollback": {
+                "default": true,
+                "description": "A boolean specifying whether a stack operation can be rolled back.",
+                "readonly": false,
+                "required": false,
+                "type": "Boolean",
+                "updatable": true
+            },
+            "environment": {
+                "default": {},
+                "description": "A map that specifies the environment used for stack operations.",
+                "readonly": false,
+                "required": false,
+                "type": "Map",
+                "updatable": true
+            },
+            "files": {
+                "default": {},
+                "description": "Contents of files referenced by the template, if any.",
+                "readonly": false,
+                "required": false,
+                "type": "Map",
+                "updatable": true
+            },
+            "parameters": {
+                "default": {},
+                "description": "Parameters to be passed to Heat for stack operations.",
+                "readonly": false,
+                "required": false,
+                "type": "Map",
+                "updatable": true
+            },
+            "template": {
+                "description": "Heat stack template.",
+                "readonly": false,
+                "required": true,
+                "type": "Map",
+                "updatable": true
+            },
+            "timeout": {
+                "description": "A integer that specifies the number of minutes that a stack operation times out.",
+                "readonly": false,
+                "required": false,
+                "type": "Integer",
+                "updatable": true
+            }
+        }
+    }
+}

api-ref/source/samples/profile-types-list-response.json

@@ -0,0 +1,10 @@
+{
+    "profile_types": [
+        {
+            "name": "os.heat.stack-1.0"
+        },
+        {
+            "name": "os.nova.server-1.0"
+        }
+    ]
+}

api-ref/source/samples/version-show-response.json

@@ -0,0 +1,19 @@
+{
+    "id": "1.0",
+    "links": [
+        {
+            "href": "/v1/",
+            "rel": "self"
+        }
+    ],
+    "max_version": "1.0",
+    "media-types": [
+        {
+            "base": "application/json",
+            "type": "application/vnd.openstack.clustering-v1+json"
+        }
+    ],
+    "min_version": "1.0",
+    "status": "CURRENT",
+    "updated": "2016-01-18T00:00:00Z"
+}

api-ref/source/samples/versions-list-response.json

@@ -0,0 +1,23 @@
+{
+    "versions": [
+        {
+            "id": "1.0",
+            "links": [
+                {
+                    "href": "/v1/",
+                    "rel": "self"
+                }
+            ],
+            "max_version": "1.0",
+            "media-types": [
+                {
+                    "base": "application/json",
+                    "type": "application/vnd.openstack.clustering-v1+json"
+                }
+            ],
+            "min_version": "1.0",
+            "status": "CURRENT",
+            "updated": "2016-01-18T00:00:00Z"
+        }
+    ]
+}

api-ref/source/versions.inc

@@ -0,0 +1,74 @@
+============
+API Versions
+============
+
+Concepts
+========
+
+The Senlin API supports a ''major versions'' expressed in request URLs and
+''microversions'' which can be sent in HTTP header ``OpenStack-API-Version``.
+
+
+List Major Versions
+===================
+
+.. rest_method::  GET /
+
+Lists information for all Clustering API major versions.
+
+
+Normal response codes: 200
+Error response codes: serviceUnavailable (503)
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - versions: versions
+
+Response Example
+----------------
+
+.. literalinclude:: samples/versions-list-response.json
+   :language: javascript
+
+
+Show Details of an API Version
+==============================
+
+.. rest_method:: GET /{version}/
+
+Show details about an API major version.
+
+Normal response codes: 200
+Error response codes: serviceUnavailable (503)
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - version: version_url
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-OpenStack-Request-ID: request_id
+  - version: version
+  - id: version_id
+  - links: version_links
+  - max_version: version_max_version
+  - media-types: version_media_types
+  - min_version: version_min_version
+  - status: version_status
+  - updated: version_updated
+
+Response Example
+----------------
+
+.. literalinclude:: samples/version-show-response.json
+   :language: javascript

tox.ini

@@ -67,11 +67,18 @@ commands = python setup.py test --coverage --testr-args="^(?!senlin\.tests\.func
 [testenv:docs]
 deps = -r{toxinidir}/test-requirements.txt
        sphinxcontrib-httpdomain
-commands = python setup.py build_sphinx
+commands =
+  python setup.py build_sphinx
+  sphinx-build -b html api-ref/source api-ref/build/html
 
 [testenv:releasenotes]
 commands = sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
 
+[testenv:api-ref]
+# options below needs an update once upstream gate/ci is ready
+install_command = pip install -U --force-reinstall {opts} {packages}
+commands =
+  sphinx-build -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html
 
 [flake8]
 ignore =