From c3b997dc77d3db46a8070aeb8d615379fabd6411 Mon Sep 17 00:00:00 2001 From: Terry Howe Date: Tue, 5 May 2015 10:25:55 -0600 Subject: [PATCH] Add some examples documentation Change-Id: I2a4a0badc7d89722aaaeefae21dd3e92e4584c8b --- doc/source/users/examples.rst | 50 +++++++++++++++++++++++++++++++++++ doc/source/users/index.rst | 2 ++ 2 files changed, 52 insertions(+) create mode 100644 doc/source/users/examples.rst diff --git a/doc/source/users/examples.rst b/doc/source/users/examples.rst new file mode 100644 index 000000000..f248f9ee0 --- /dev/null +++ b/doc/source/users/examples.rst @@ -0,0 +1,50 @@ +OpenStack SDK Examples +====================== + +An effort has been made to provide some useful examples to try out the +SDK. These examples reside in the examples directory of the project. +The examples use an authentication configuration that is very similar +to the configuration used for most OpenStack clients. + +Configuration +------------- + +Most of the examples use a common argument parser to collect +authentication information to run requests. The authentication may come +from the OS prefixed environment variables similar to the ones used in many +client libraries or you may use +`os-client-config `_. + +To use the OS prefixed environment variables, set up something similar to +the following.:: + + export OS_REGION_NAME=Manhattan + export OS_PROJECT_NAME=beasties + export OS_IDENTITY_API_VERSION=2.0 + export OS_PASSWORD=horovitz + export OS_AUTH_URL=https://127.0.0.1:5000/v2.0/ + export OS_USERNAME=adrock + +To use os-client-config, create a clouds.yaml file, which typically resides in +~/.config/openstack/clouds.yaml to store authentication and preference +information. If you are using os-client-config, you can use the OS_CLOUD +environment variable or use the --os-cloud command line option to specify +the cloud you want to use.:: + + export OS_CLOUD=miked + +Running +------- + +Once you have a configuration, most examples can be run by calling them +directly. For example, the list example can be run by just passing it the +name of the resource you want to list:: + + python examples/list.py openstack/compute/v2/flavor.py + +The example code uses some logic to parse the file name and generate a +resource class name. That may not work if the resource class name does +not match the file name. If that is the case, you will need to specify +the resource module name:: + + python examples/list.py openstack.network.v2.floating_ip.FloatingIP diff --git a/doc/source/users/index.rst b/doc/source/users/index.rst index 6d589dcad..f8d47ad41 100644 --- a/doc/source/users/index.rst +++ b/doc/source/users/index.rst @@ -37,6 +37,8 @@ approach, this is where you'll want to begin. Telemetry Volume +It may also be useful to try out some working code `examples `_. + API Documentation -----------------