diff --git a/doc-tools-check-languages.conf b/doc-tools-check-languages.conf index 3b1bf86796..adc2fe8b42 100644 --- a/doc-tools-check-languages.conf +++ b/doc-tools-check-languages.conf @@ -24,6 +24,7 @@ declare -A SPECIAL_BOOKS=( # This needs special handling, handle it with the RST tools. ["common"]="RST" ["glossary"]="RST" + ["api-quick-start"]="RST" ["image-guide"]="RST" ["install-guide"]="RST" # Do not translate diff --git a/doc/api-quick-start/setup.cfg b/doc/api-quick-start/setup.cfg new file mode 100644 index 0000000000..34094724b5 --- /dev/null +++ b/doc/api-quick-start/setup.cfg @@ -0,0 +1,22 @@ +[metadata] +name = OpenStack API Documentation +summary = OpenStack API Documentation +description-file = + README.rst +author = OpenStack Documentation +author-email = openstack-docs@lists.openstack.org +home-page = https://developer.openstack.org/ +classifier = + Intended Audience :: Developers + License :: OSI Approved :: Apache Software License + +[build_sphinx] +all_files = 1 +build-dir = build +source-dir = source + +[pbr] +warnerrors = True + +[wheel] +universal = 1 diff --git a/doc/api-quick-start/setup.py b/doc/api-quick-start/setup.py new file mode 100755 index 0000000000..ed58d0f26c --- /dev/null +++ b/doc/api-quick-start/setup.py @@ -0,0 +1,6 @@ +#!/usr/bin/env python +import setuptools + +setuptools.setup( + setup_requires=['pbr'], + pbr=True) diff --git a/doc/api-quick-start/source/api-quick-start.rst b/doc/api-quick-start/source/api-quick-start.rst new file mode 100644 index 0000000000..b645d89894 --- /dev/null +++ b/doc/api-quick-start/source/api-quick-start.rst @@ -0,0 +1,575 @@ +.. _openstack_API_quick_guide: + +============== +OpenStack APIs +============== + +To authenticate access to OpenStack services, you must first issue an +authentication request with a payload of credentials to OpenStack Identity to +get an authentication token. + +Credentials are usually a combination of your user name and password, +and optionally, the name or ID of the project of your cloud. +Ask your cloud administrator for your user name, password, and project so +that you can generate authentication tokens. Alternatively, you can +supply a token rather than a user name and password. + +When you send API requests, you include the token in the ``X-Auth-Token`` +header. If you access multiple OpenStack services, you must get a token for +each service. A token is valid for a limited time before it expires. A token +can also become invalid for other reasons. For example, if the roles for a +user change, existing tokens for that user are no longer valid. + +Authentication and API request workflow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Request an authentication token from the Identity endpoint that your + cloud administrator gave you. Send a payload of credentials in the + request as shown in :ref:`authenticate`. If the request succeeds, the server + returns an authentication token. + +#. Send API requests and include the token in the ``X-Auth-Token`` + header. Continue to send API requests with that token until the service + completes the request or the Unauthorized (401) error occurs. + +#. If the Unauthorized (401) error occurs, request another token. + +The examples in this section use cURL commands. For information about cURL, +see http://curl.haxx.se/. For information about the OpenStack APIs, see +:ref:`current_api_versions`. + + +.. _authenticate: + +Authenticate +~~~~~~~~~~~~ + +The payload of credentials to authenticate contains these parameters: + ++-----------------------+----------------+--------------------------------------+ +| Parameter | Type | Description | ++=======================+================+======================================+ +| *User Domain* | string | The Domain of the user. | +| (required) | | | ++-----------------------+----------------+--------------------------------------+ +| username (required) | string | The user name. If you do not provide | +| | | a user name and password, you must | +| | | provide a token. | ++-----------------------+----------------+--------------------------------------+ +| password (required) | string | The password for the user. | ++-----------------------+----------------+--------------------------------------+ +| *Project Domain* | string | The Domain of the project. This is a | +| (optional) | | required part of the scope object. | ++-----------------------+----------------+--------------------------------------+ +| *Project Name* | string | The project name. Both the | +| (optional) | | *Project ID* and *Project Name* | +| | | are optional. | ++-----------------------+----------------+--------------------------------------+ +| *Project ID* | string | The project ID. Both the *project ID*| +| (optional) | | and *Project Name* are optional. But | +| | | one of them is required along with | +| | | the *Project Domain*. They are | +| | | wrapped under a scope object. | +| | | If you do not know the project name | +| | | or ID, send a request without any | +| | | scope object. | ++-----------------------+----------------+--------------------------------------+ + + +In a typical OpenStack deployment that runs Identity, you can specify your +project name, and user name and password credentials to authenticate. + +First, export your project name to the ``OS_PROJECT_NAME`` environment variable, +your project domain name to the ``OS_PROJECT_DOMAIN_NAME`` environment variable, +your user name to the ``OS_USERNAME`` environment variable, your password to the +``OS_PASSWORD`` environment variable and your user domain name to the +``OS_USER_DOMAIN_NAME`` environment variable. + +The example below uses an endpoint from an installation of Ocata by following +the installation guide. However, you can also use ``$OS_AUTH_URL`` as an +environment variable as needed to change the URL. + +Then, run this cURL command to request a token: + +.. code-block:: console + + $ curl -v -s -X POST $OS_AUTH_URL/auth/tokens?nocatalog -H "Content-Type: application/json" -d '{ "auth": { "identity": { "methods": ["password"],"password": {"user": {"domain": {"name": "'"$OS_USER_DOMAIN_NAME"'"},"name": "'"$OS_USERNAME"'", "password": "'"$OS_PASSWORD"'"} } }, "scope": { "project": { "domain": { "name": "'"$OS_PROJECT_DOMAIN_NAME"'" }, "name": "'"$OS_PROJECT_NAME"'" } } }}' \ + | python -m json.tool + +If the request succeeds, it returns the ``Created (201)`` response code +along with the token as a value in the ``X-Subject-Token`` response header. +The header is followed by a response body that has an object of type +``token`` which has the token expiration date and time in the form +``"expires_at":"datetime"`` along with other attributes. + +The following example shows a successful response: + +.. code-block:: console + + * Trying 192.168.56.101... + * Connected to controller (192.168.56.101) port 5000 (#0) + > POST /v3/auth/tokens?nocatalog HTTP/1.1 + > Host: controller:5000 + > User-Agent: curl/7.47.0 + > Accept: */* + > Content-Type: application/json + > Content-Length: 226 + > + } [226 bytes data] + * upload completely sent off: 226 out of 226 bytes + < HTTP/1.1 201 Created + < Date: Fri, 26 May 2017 06:48:58 GMT + < Server: Apache/2.4.18 (Ubuntu) + < X-Subject-Token: gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99BHrjdSGai--_-JstU3WazsFXmRHNbD07qOQKTp5Sen2R_b9csaDkU49VXqSaJ0jh2nAlwJkys8aazz2oa3xSeUVe3Ndv_HRiW23-iWTr6jquK_AXdhRX7nvM4lmVTrxXFpelnJQ + < Vary: X-Auth-Token + < X-Distribution: Ubuntu + < x-openstack-request-id: req-0e9239ec-104b-40e0-a337-dca91fb24387 + < Content-Length: 521 + < Content-Type: application/json + < + { [521 bytes data] + * Connection #0 to host controller left intact + { + "token": { + "audit_ids": [ + "HOGlhnMFT52xY7PjbuJZlA" + ], + "expires_at": "2017-05-26T07:48:58.000000Z", + "is_domain": false, + "issued_at": "2017-05-26T06:48:58.000000Z", + "methods": [ + "password" + ], + "project": { + "domain": { + "id": "default", + "name": "Default" + }, + "id": "05ef0bf2a79c42b2b8155873b6404061", + "name": "demo" + }, + "roles": [ + { + "id": "b18239b7026042ef8695c3c4cf10607b", + "name": "user" + } + ], + "user": { + "domain": { + "id": "default", + "name": "Default" + }, + "id": "12846256e60c42f88d0e1ba9711a57f5", + "name": "demo", + "password_expires_at": null + } + } + } + + +.. note:: + In the above request, the query string ``nocatalog`` is used as you + just want to get a token and do not want the service catalog + (if it is available for the user) cluttering the output. + If a user wants to get the service catalog, this query string need + not be appended to the URL. + +Send API requests +~~~~~~~~~~~~~~~~~ + +This section shows how to make some basic Compute API calls. For a complete +list of Compute API calls, see +`Compute API `__. + +Export the token ID to the ``OS_TOKEN`` environment variable. For example: + +.. code-block:: console + + export OS_TOKEN=gAAAAABZJ8_a7aiq1SnOhbNw8vFb5WZChcvWdzzUAFzhiB99BHrjdSGai--_-JstU3WazsFXmRHNbD07qOQKTp5Sen2R_b9csaDkU49VXqSaJ0jh2nAlwJkys8aazz2oa3xSeUVe3Ndv_HRiW23-iWTr6jquK_AXdhRX7nvM4lmVTrxXFpelnJQ + +The token expires every hour by default, +though it can be configured differently - see +the `expiration `__ option in the +the *Identity Service Configuration Guide*. + +Export the project name to the ``OS_PROJECT_NAME`` environment variable. For example: + +.. code-block:: console + + export OS_PROJECT_NAME=demo + +Then, use the Compute API to list flavors, substituting the Compute API endpoint with +one containing your project ID below: + +.. code-block:: console + + $ curl -s -H "X-Auth-Token: $OS_TOKEN" \ + $OS_COMPUTE_API/flavors \ + | python -m json.tool + +.. code-block:: json + + { + "flavors": [ + { + "id": "1", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/1", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/1", + "rel": "bookmark" + } + ], + "name": "m1.tiny" + }, + { + "id": "2", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/2", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/2", + "rel": "bookmark" + } + ], + "name": "m1.small" + }, + { + "id": "3", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/3", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/3", + "rel": "bookmark" + } + ], + "name": "m1.medium" + }, + { + "id": "4", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/4", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/4", + "rel": "bookmark" + } + ], + "name": "m1.large" + }, + { + "id": "5", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/flavors/5", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/flavors/5", + "rel": "bookmark" + } + ], + "name": "m1.xlarge" + } + ] + } + +Export the $OS_PROJECT_ID from the token call, and then +use the Compute API to list images: + +.. code-block:: console + + $ curl -s -H "X-Auth-Token: $OS_TOKEN" \ + http://8.21.28.222:8774/v2/$OS_PROJECT_ID/images \ + | python -m json.tool + +.. code-block:: json + + { + "images": [ + { + "id": "2dadcc7b-3690-4a1d-97ce-011c55426477", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477", + "rel": "bookmark" + }, + { + "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/2dadcc7b-3690-4a1d-97ce-011c55426477", + "type": "application/vnd.openstack.image", + "rel": "alternate" + } + ], + "name": "Fedora 21 x86_64" + }, + { + "id": "cfba3478-8645-4bc8-97e8-707b9f41b14e", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e", + "rel": "bookmark" + }, + { + "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/cfba3478-8645-4bc8-97e8-707b9f41b14e", + "type": "application/vnd.openstack.image", + "rel": "alternate" + } + ], + "name": "Ubuntu 14.04 amd64" + }, + { + "id": "2e4c08a9-0ecd-4541-8a45-838479a88552", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552", + "rel": "bookmark" + }, + { + "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/2e4c08a9-0ecd-4541-8a45-838479a88552", + "type": "application/vnd.openstack.image", + "rel": "alternate" + } + ], + "name": "CentOS 7 x86_64" + }, + { + "id": "c8dd9096-60c1-4e23-a486-82955481df9f", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f", + "rel": "bookmark" + }, + { + "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/c8dd9096-60c1-4e23-a486-82955481df9f", + "type": "application/vnd.openstack.image", + "rel": "alternate" + } + ], + "name": "CentOS 6.5 x86_64" + }, + { + "id": "f97b8d36-935e-4666-9c58-8a0afc6d3796", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796", + "rel": "bookmark" + }, + { + "href": "http://8.21.28.222:9292/f9828a18c6484624b571e85728780ba8/images/f97b8d36-935e-4666-9c58-8a0afc6d3796", + "type": "application/vnd.openstack.image", + "rel": "alternate" + } + ], + "name": "Fedora 20 x86_64" + } + ] + } + +Export the $OS_PROJECT_ID from the token call, and then +use the Compute API to list servers: + +.. code-block:: console + + $ curl -s -H "X-Auth-Token: $OS_TOKEN" \ + http://8.21.28.222:8774/v2/$OS_PROJECT_ID/servers \ + | python -m json.tool + +.. code-block:: json + + { + "servers": [ + { + "id": "41551256-abd6-402c-835b-e87e559b2249", + "links": [ + { + "href": "http://8.21.28.222:8774/v2/f8828a18c6484624b571e85728780ba8/servers/41551256-abd6-402c-835b-e87e559b2249", + "rel": "self" + }, + { + "href": "http://8.21.28.222:8774/f8828a18c6484624b571e85728780ba8/servers/41551256-abd6-402c-835b-e87e559b2249", + "rel": "bookmark" + } + ], + "name": "test-server" + } + ] + } + +.. _client-intro: + +OpenStack command-line clients +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For scripting work and simple requests, you can use a command-line client like +the ``openstack-client`` client. This client enables you to use the Identity, +Compute, Block Storage, and Object Storage APIs through a command-line +interface. Also, each OpenStack project has a related client project that +includes Python API bindings and a command-line interface (CLI). + +For information about the command-line clients, see `OpenStack +Command-Line Interface Reference `__. + +Install the clients +------------------- + +Use ``pip`` to install the OpenStack clients on a Mac OS X or Linux system. It +is easy and ensures that you get the latest version of the client from the +`Python Package Index `__. Also, ``pip`` lets you +update or remove a package. + +You must install the client for each project separately, but the +``python-openstackclient`` covers multiple projects. + +Install or update a client package: + +.. code-block:: console + + $ sudo pip install [--upgrade] python-PROJECTclient + +Where *PROJECT* is the project name. + +For example, install the ``openstack`` client: + +.. code-block:: console + + $ sudo pip install python-openstackclient + +To update the ``openstack`` client, run this command: + +.. code-block:: console + + $ sudo pip install --upgrade python-openstackclient + +To remove the ``openstack`` client, run this command: + +.. code-block:: console + + $ sudo pip uninstall python-openstackclient + +Before you can issue client commands, you must download and source the +``openrc`` file to set environment variables. + +For complete information about the OpenStack clients, including how to source +the ``openrc`` file, see `OpenStack End User Guide `__, +`OpenStack Administrator Guide `__, +and `OpenStack Command-Line Interface Reference `__. + +Launch an instance +------------------ + +To launch instances, you must choose a name, an image, and a flavor for +your instance. + +To list available images, call the Compute API through the ``openstack`` +client: + +.. code-block:: console + + $ openstack image list + +.. code-block:: console + + +--------------------------------------+------------------+ + | ID | Name | + +--------------------------------------+------------------+ + | a5604931-af06-4512-8046-d43aabf272d3 | fedora-20.x86_64 | + +--------------------------------------+------------------+ + +To list flavors, run this command: + +.. code-block:: console + + $ openstack flavor list + +.. code-block:: console + + +----+-----------+-----------+------+-----------+------+-------+-----------+ + | ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | Is_Public | + +----+-----------+-----------+------+-----------+------+-------+-----------+ + | 1 | m1.tiny | 512 | 0 | 0 | | 1 | True | + | 2 | m1.small | 2048 | 20 | 0 | | 1 | True | + | 3 | m1.medium | 4096 | 40 | 0 | | 2 | True | + | 4 | m1.large | 8192 | 80 | 0 | | 4 | True | + | 42 | m1.nano | 64 | 0 | 0 | | 1 | True | + | 5 | m1.xlarge | 16384 | 160 | 0 | | 8 | True | + | 84 | m1.micro | 128 | 0 | 0 | | 1 | True | + +----+-----------+-----------+------+-----------+------+-------+-----------+ + +To launch an instance, note the IDs of your desired image and flavor. + +To launch the ``my_instance`` instance, run the ``openstack server create`` +command with the image and flavor IDs and the server name: + +.. code-block:: console + + $ openstack server create --image a5604931-af06-4512-8046-d43aabf272d3 --flavor 1 my_instance + +.. code-block:: console + + +--------------------------------------+---------------------------------------------------------+ + | Field | Value | + +--------------------------------------+---------------------------------------------------------+ + | OS-DCF:diskConfig | MANUAL | + | OS-EXT-AZ:availability_zone | nova | + | OS-EXT-STS:power_state | 0 | + | OS-EXT-STS:task_state | scheduling | + | OS-EXT-STS:vm_state | building | + | OS-SRV-USG:launched_at | None | + | OS-SRV-USG:terminated_at | None | + | accessIPv4 | | + | accessIPv6 | | + | addresses | | + | adminPass | 3vgzpLzChoac | + | config_drive | | + | created | 2015-08-27T03:02:27Z | + | flavor | m1.tiny (1) | + | hostId | | + | id | 1553694c-d711-4954-9b20-84b8cb4598c6 | + | image | fedora-20.x86_64 (a5604931-af06-4512-8046-d43aabf272d3) | + | key_name | None | + | name | my_instance | + | os-extended-volumes:volumes_attached | [] | + | progress | 0 | + | project_id | 9f0e4aa4fd3d4b0ea3184c0fe7a32210 | + | properties | | + | security_groups | [{u'name': u'default'}] | + | status | BUILD | + | updated | 2015-08-27T03:02:28Z | + | user_id | b3ce0cfc170641e98ff5e42b1be9c85a | + +--------------------------------------+---------------------------------------------------------+ + +.. note:: + For information about the default ports that the OpenStack components use, + see `Firewalls and default ports `_ + in the *OpenStack Installation Guide*. + diff --git a/doc/api-quick-start/source/conf.py b/doc/api-quick-start/source/conf.py new file mode 100644 index 0000000000..a26db5a130 --- /dev/null +++ b/doc/api-quick-start/source/conf.py @@ -0,0 +1,296 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +import subprocess + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['openstackdocstheme'] + +# Add any paths that contain templates here, relative to this directory. +# templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +repository_name = 'openstack/api-site' +project = u'Openstack-API-Documentation' +bug_project = 'openstack-api-site' +bug_tag = u'api-site' +copyright = u'2017, OpenStack contributors' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.1' +# The full version, including alpha/beta/rc tags. +release = '0.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'openstackdocs' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# To use the API Reference sidebar dropdown menu, +# uncomment the html_theme_options parameter. The theme +# variable, sidebar_dropdown, should be set to `api_ref`. +# Otherwise, the list of links for the User and Ops docs +# appear in the sidebar dropdown menu. +html_theme_options = {"sidebar_dropdown": "api_ref", + "sidebar_mode": "toc"} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [openstackdocstheme.get_html_theme_path()] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +# html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# So that we can enable "log-a-bug" links from each output HTML page, this +# variable must be set to a format that includes year, month, day, hours and +# minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_domain_indices = True + +# If false, no index is generated. +html_use_index = False + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# This one is needed for "Report a bug". +html_show_sourcelink = False + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'OpenStack-API-Documentation' + +# If true, publish source files +html_copy_source = False + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # 'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'OpenStackAPI.tex', u'OpenStack API Documentation', + u'OpenStack Doc Team', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# If true, show page references after internal links. +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'openstack-api-documentation', u'OpenStack API Documentation', + [u'OpenStack Doc Team'], 1) +] + +# If true, show URL addresses after external links. +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'openstack-api-documentation', u'OpenStack API Documentation', + u'OpenStack Doc Team', 'OpenStackAPIDocs', 'Describes OpenStack API reference and concepts.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# texinfo_appendices = [] + +# If false, no module index is generated. +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# texinfo_no_detailmenu = False + +# Set to True to enable printing of the TODO sections +todo_include_todos = False + +# -- Options for Internationalization output ------------------------------ +locale_dirs = ['locale/'] + +# -- Options for PDF output -------------------------------------------------- + +pdf_documents = [ + ('index', u'openstack-api-documentation', u'OpenStack API Documentation', + u'OpenStack contributors') +] diff --git a/doc/api-quick-start/source/index.rst b/doc/api-quick-start/source/index.rst new file mode 100644 index 0000000000..f835fc76f7 --- /dev/null +++ b/doc/api-quick-start/source/index.rst @@ -0,0 +1,173 @@ +=========================== +OpenStack API Documentation +=========================== + +Use the OpenStack APIs to launch server instances, create images, assign +metadata to instances and images, create storage containers and objects, and +complete other actions in your OpenStack cloud. + +.. note:: + The links below are grouped according to the API status that reflects the + state of the endpoint on the service. + + * 'Current' indicates a stable version that is up-to-date, recent, and + might receive future versions. This endpoint should be prioritized over + all others. + * 'Supported' is a stable version that is available on the server. + However, it is not likely the most recent available and might not be + updated or might be deprecated at some time in the future. + * 'Deprecated' is a stable version that is still available but is being + deprecated and might be removed in the future. + * 'Experimental' is not a stable version. This version is under + development or contains features that are otherwise subject to change. + + For more information about API status values and version information, see + `Version Discovery `__. + + The notation '(microversions)' next to the link to an API reference + indicates that the API follows a `pattern established by the Compute + service + `__ + to enable small, documented changes to the API on a resource-by-resource + basis. + +.. _current_api_versions: + +Current API versions +-------------------- + +`Acceleration API v1 `__ + +`Application Catalog API v1 `__ + +`Application Container Service API `__ (microversions) + +`Backup API v1 `__ + +`Bare Metal API v1 `__ (microversions) + +`Block Storage API v3 `__ (microversions) + +.. note:: The Block Storage API v3 is functionally identical to the + Block Storage API v2. Subsequent API v3 microversions, such as v3.1, + differ from API v2. + +`Clustering API v1 `__ + +`Compute API `__ (microversions) + +`Container Infrastructure Management API `__ (microversions) + +`Data Processing v1.1 `__ + +`Data Protection Orchestration v1 `__ + +`Database Service API v1.0 `__ + +`Domain Name Server (DNS) API v2 `__ + +`EC2 API Service `__ + +`Function Engine `__ + +`Identity API v3 `__ + +`Identity API v3 extensions `__ + +`Image service API v2 `__ + +`Key Manager API v1 `__ + +`Load Balancer API v2 `__ + +`Messaging API v2 `__ + +`Networking API v2.0 `__ + +`NFV Orchestration API v1.0 `__ + +`Object Storage API v1 `__ + +`Orchestration API v1 `__ + +`Placement API `__ (microversions) + +`Resource Optimization API v1 `__ + +`Search API v1 `__ + +`Shared File Systems API v2 `__ (microversions) + +.. note:: The Shared File Systems API v1 is functionally identical to the + Shared File Systems API v2. Subsequent API v2 microversions, such as v2.1, + differ from API v1. + +Supported API versions +---------------------- + + +Deprecated API versions +----------------------- + +`Block Storage API v2 `__ + +.. note:: The Block Storage API v3 is functionally identical to the + Block Storage API v2. Subsequent API v3 microversions, such as v3.1, + differ from API v2. + +`Identity API v2.0 extensions `__ + +.. todo: telemetry link + +API quick-start examples +------------------------ + +With the `TryStack `__ OpenStack +installation, these services work together in the background of the +installation, and many of these examples work on TryStack. + +After you authenticate through Identity, you can use the other OpenStack +APIs to create and manage resources in your OpenStack cloud. You can +launch instances from images and assign metadata to instances through +the Compute API or the **openstack** command-line client. + +To begin sending API requests, use one of the following methods: + +- **cURL** + + A command-line tool that lets you send HTTP requests and receive + responses. See the section called :ref:`openstack_API_quick_guide`. + +- **OpenStack command-line client** + + The OpenStack project provides a command-line client that enables + you to access APIs through easy-to-use commands. See the section + called :ref:`client-intro`. + +- **REST clients** + + Both Mozilla and Google provide browser-based graphical interfaces + for REST. For Firefox, see + `RESTClient `__. + For Chrome, see + `rest-client `__. + +- **OpenStack Python Software Development Kit (SDK)** + + Use this SDK to write Python automation scripts that create and + manage resources in your OpenStack cloud. The SDK implements Python + bindings to the OpenStack API, which enables you to perform + automation tasks in Python by making calls on Python objects rather + than making REST calls directly. All OpenStack command-line tools are + implemented by using the Python SDK. See `OpenStack Python + SDK `__ in the + *OpenStack End User Guide*. + +.. toctree:: + :maxdepth: 2 + + api-quick-start + + + + diff --git a/doc/doc-contrib-guide/source/api-guides.rst b/doc/doc-contrib-guide/source/api-guides.rst index 5a8f90d651..e83733132d 100644 --- a/doc/doc-contrib-guide/source/api-guides.rst +++ b/doc/doc-contrib-guide/source/api-guides.rst @@ -191,7 +191,7 @@ documentation, patch the ``reference/projects.yaml`` file in the .. _`example patch`: https://review.opendev.org/#/c/233446/ .. _`API documentation guidelines`: https://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html .. _`microversions`: https://developer.openstack.org/api-guide/compute/microversions.html -.. _`API Quick Start page`: https://developer.openstack.org/api-guide/quick-start/ +.. _`API Quick Start page`: https://docs.openstack.org/api-quick-start/ .. _`cycle-with-milestones release model`: https://releases.openstack.org/reference/release_models.html#cycle-with-milestones .. _`nova example`: https://github.com/openstack/nova/blob/master/api-ref/source/conf.py .. _`openstack/api-site repository`: https://opendev.org/openstack/api-site/src/branch/master/api-quick-start/source/index.rst diff --git a/tools/build-all-rst.sh b/tools/build-all-rst.sh index 7a1586e6e0..ad878f8613 100755 --- a/tools/build-all-rst.sh +++ b/tools/build-all-rst.sh @@ -31,7 +31,7 @@ PDF_TARGETS=( 'image-guide' \ 'install-guide') for guide in doc-contrib-guide glossary \ - image-guide install-guide; do + api-quick-start image-guide install-guide; do if [[ ${PDF_TARGETS[*]} =~ $guide ]]; then tools/build-rst.sh doc/$guide --build build \ --target $guide $LINKCHECK $PDF_OPTION diff --git a/tox.ini b/tox.ini index 6f429f806f..d789bf0262 100644 --- a/tox.ini +++ b/tox.ini @@ -95,7 +95,7 @@ usedevelop = False [doc8] # Settings for doc8: # Ignore target directories and autogenerated files -ignore-path = doc/*/target,doc/*/build* +ignore-path = doc/*/target,doc/*/build*,doc/api-quick-start/source/api-quick-start.rst # File extensions to use extensions = .rst,.txt # Maximal line length should be 79 but we have some overlong lines.