openstack/openstack-manuals
Code Issues Proposed changes

[user-guide] Reorganize SDK section

Browse Source 
The current structure of SDK section is not well listed in the
toc tree. This commit moves the overview in sdk.rst to a sub page
sdk_overview.rst so that all subsections in SDK section are displayed
in the toc.

Also moves 'Create a legacy client object' page to upper level.
Previously this page is listed as a bullet in the authenticate page
so it was small. This change makes the page more highlighed.

Change-Id: I6414b748a77a6375423da38e52113b36359e5f7d
This commit is contained in:
Akihiro Motoki 2016-06-16 10:24:09 +09:00 committed by Olena Logvinova
parent 36055121c1
commit 98f84a360f
3 changed files with 62 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
doc/user-guide/source/sdk.rst
View File

@ -2,68 +2,13 @@
OpenStack Python SDK
====================
OpenStack provides four different options for interacting with its
APIs from Python, each targetting a slightly different user.
- OpenStack SDK
- shade
- Per-project client libraries
- Direct REST calls via keystoneauth
You should also be familiar with:
- RESTful web services
- HTTP/1.1
- JSON and data serialization formats
OpenStack SDK
-------------
The `OpenStack Python Software Development Kit (SDK)
<https://pypi.python.org/pypi/openstacksdk>`_ is used 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.
New users should default to coding against the OpenStack SDK.
shade
-----
`shade <http://pypi.python.org/pypi/shade>`_ is a an abstraction library
focused on hiding implementation differences between OpenStack clouds. While
the OpenStack SDK presents a clean object interface to the underlying REST
APIs, shade hides them if doing so is advantageous. If you plan on
running the same python program against many OpenStack clouds, you may want to
use shade - but if you need to access any features of a cloud that do not have
an cloud-neutral abstraction mapping, you will be unable to do so with shade.
Per-project client libraries
----------------------------
Each OpenStack project produces a client library that wraps its own REST API.
Unless there is no other choice for some reason, the per-project libraries
should be avoided.
Direct REST calls via keystoneauth
----------------------------------
All of OpenStack's APIs are actually REST APIs. The
`keystoneauth <http://docs.openstack.org/developer/keystoneauth>`_ library
provides an object that looks very much like a
`Session <http://docs.python-requests.org/en/master/api/#request-sessions>`_
object from the Python
`requests <http://pypi.python.org/pypi/requests>`_ library that handles all
of the authentication for you. If you are more comfortable just dealing with
REST, or if there is a feature implemented in your cloud that has not seen
support in any of the libraries yet, this option is for you.
.. toctree::
:maxdepth: 2
sdk_overview.rst
sdk_install.rst
sdk_authenticate.rst
sdk_create_legacy_novaclient.rst
sdk_manage_images.rst
sdk_assign_cors_headers.rst
sdk_schedule_objects_for_deletion.rst

5
doc/user-guide/source/sdk_authenticate.rst
View File

@ -21,8 +21,3 @@ and only one cloud account, they are the most convenient way.
``clouds.yaml`` is a bit newer and was designed to help folks who have
more than one OpenStack cloud that they are using.
.. toctree::
:maxdepth: 2
sdk_create_legacy_novaclient.rst

60
doc/user-guide/source/sdk_overview.rst Normal file
View File

@ -0,0 +1,60 @@
========
Overview
========
OpenStack provides four different options for interacting with its
APIs from Python, each targetting a slightly different user:
- OpenStack SDK
- shade
- Per-project client libraries
- Direct REST calls via keystoneauth
You should also be familiar with:
- RESTful web services
- HTTP/1.1
- JSON and data serialization formats
OpenStack SDK
-------------
The `OpenStack Python Software Development Kit (SDK)
<https://pypi.python.org/pypi/openstacksdk>`_ is used 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.
New users should default to coding against the OpenStack SDK.
shade
-----
`shade <http://pypi.python.org/pypi/shade>`_ is a an abstraction library
focused on hiding implementation differences between OpenStack clouds. While
the OpenStack SDK presents a clean object interface to the underlying REST
APIs, shade hides them if doing so is advantageous. If you plan on
running the same Python program against many OpenStack clouds, you may want to
use shade - but if you need to access any features of a cloud that do not have
a cloud-neutral abstraction mapping, you will be unable to do so with shade.
Per-project client libraries
----------------------------
Each OpenStack project produces a client library that wraps its own REST API.
Unless there is no other choice for some reason, the per-project libraries
should be avoided.
Direct REST calls via keystoneauth
----------------------------------
All of OpenStack's APIs are actually REST APIs. The
`keystoneauth <http://docs.openstack.org/developer/keystoneauth>`_ library
provides an object that looks very much like a
`Session <http://docs.python-requests.org/en/master/api/#request-sessions>`_
object from the Python
`requests <http://pypi.python.org/pypi/requests>`_ library that handles all
of the authentication for you. If you are more comfortable just dealing with
REST or if there is a feature implemented in your cloud that has not seen
support in any of the libraries yet, this option is for you.