diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index d9573fde1..e55b1d7a7 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -1,9 +1,10 @@ +================================= Contributing to the OpenStack SDK ================================= This section of documentation pertains to those who wish to contribute to the development of this SDK. If you're looking for documentation on how to use -the SDK to build applications, please see the `user <../user>`_ section. +the SDK to build applications, refer to the `user <../user>`_ section. About the Project ----------------- @@ -30,22 +31,24 @@ Contacting the Developers ------------------------- IRC -*** +~~~ -The developers of this project are available in the -`#openstack-sdks `_ -channel on Freenode. This channel includes conversation on SDKs and tools -within the general OpenStack community, including OpenStackClient as well -as occasional talk about SDKs created for languages outside of Python. +The developers of this project are available in the `#openstack-sdks`__ channel +on Freenode. This channel includes conversation on SDKs and tools within the +general OpenStack community, including OpenStackClient as well as occasional +talk about SDKs created for languages outside of Python. + +.. __: http://webchat.freenode.net?channels=%23openstack-sdks Email -***** +~~~~~ -The `openstack-discuss `_ -mailing list fields questions of all types on OpenStack. Using the -``[sdk]`` filter to begin your email subject will ensure +The `openstack-discuss`__ mailing list fields questions of all types on +OpenStack. Using the ``[sdk]`` filter to begin your email subject will ensure that the message gets to SDK developers. +.. __: mailto:openstack-discuss@openstack.org?subject=[sdk]%20Question%20about%20openstacksdk + Coding Standards ---------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index 19b9bdead..c5a8c5d3a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,12 +1,13 @@ -Welcome to the OpenStack SDK! -============================= +============ +openstacksdk +============ This documentation is split into three sections: -* an :doc:`installation ` guide -* a section for :doc:`users ` looking to build applications +* An :doc:`installation ` guide +* A section for :doc:`users ` looking to build applications which make use of OpenStack -* a section for those looking to :doc:`contribute ` +* A section for those looking to :doc:`contribute ` to this project Installation @@ -33,8 +34,6 @@ For Contributors contributor/index -.. include:: ../../README.rst - General Information ------------------- diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index fcbfcb74a..49cf87d5d 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,12 +1,18 @@ -============ -Installation -============ +================== +Installation guide +================== -At the command line:: +The OpenStack SDK is available on `PyPI`__ under the name **openstacksdk**. To +install it, use ``pip``: - $ pip install openstacksdk +.. code-block:: bash -Or, if you have virtualenv wrapper installed:: + $ pip install openstacksdk - $ mkvirtualenv openstacksdk - $ pip install openstacksdk +To check the installed version you can call the module with: + +.. code-block:: bash + + $ python -m openstack version + +.. __: https://pypi.org/project/openstacksdk diff --git a/doc/source/user/config/configuration.rst b/doc/source/user/config/configuration.rst index 36fbf3bb2..d6fb958b3 100644 --- a/doc/source/user/config/configuration.rst +++ b/doc/source/user/config/configuration.rst @@ -34,9 +34,9 @@ Config Files `openstacksdk` will look for a file called `clouds.yaml` in the following locations: -* Current Directory -* ~/.config/openstack -* /etc/openstack +* ``.`` (the current directory) +* ``$HOME/.config/openstack`` +* ``/etc/openstack`` The first file found wins. diff --git a/doc/source/user/guides/intro.rst b/doc/source/user/guides/intro.rst new file mode 100644 index 000000000..ac53905e4 --- /dev/null +++ b/doc/source/user/guides/intro.rst @@ -0,0 +1,102 @@ +=============== +Getting started +=============== + +openstacksdk aims to talk to any OpenStack cloud. To do this, it requires a +configuration file. openstacksdk favours ``clouds.yaml`` files, but can also +use environment variables. The ``clouds.yaml`` file should be provided by your +cloud provider or deployment tooling. An example: + +.. code-block:: yaml + + clouds: + mordred: + region_name: Dallas + auth: + username: 'mordred' + password: XXXXXXX + project_name: 'demo' + auth_url: 'https://identity.example.com' + +More information on configuring openstacksdk can be found in +:doc:`/user/config/configuration`. + +Given sufficient configuration, you can use openstacksdk to interact with your +cloud. openstacksdk consists of three layers. Most users will make use of the +*proxy* layer. Using the above ``clouds.yaml``, consider listing servers: + +.. code-block:: python + + import openstack + + # Initialize and turn on debug logging + openstack.enable_logging(debug=True) + + # Initialize connection + conn = openstack.connect(cloud='mordred') + + # List the servers + for server in conn.compute.servers(): + print(server.to_dict()) + +openstacksdk also contains a higher-level *cloud* layer based on logical +operations: + +.. code-block:: python + + import openstack + + # Initialize and turn on debug logging + openstack.enable_logging(debug=True) + + # Initialize connection + conn = openstack.connect(cloud='mordred') + + # List the servers + for server in conn.list_servers(): + print(server.to_dict()) + +The benefit of this layer is mostly seen in more complicated operations that +take multiple steps and where the steps vary across providers. For example: + +.. code-block:: python + + import openstack + + # Initialize and turn on debug logging + openstack.enable_logging(debug=True) + + # Initialize connection + conn = openstack.connect(cloud='mordred') + + # Upload an image to the cloud + image = conn.create_image( + 'ubuntu-trusty', filename='ubuntu-trusty.qcow2', wait=True) + + # Find a flavor with at least 512M of RAM + flavor = conn.get_flavor_by_ram(512) + + # Boot a server, wait for it to boot, and then do whatever is needed + # to get a public IP address for it. + conn.create_server( + 'my-server', image=image, flavor=flavor, wait=True, auto_ip=True) + +Finally, there is the low-level *resource* layer. This provides support for the +basic CRUD operations supported by REST APIs and is the base building block for +the other layers. You typically will not need to use this directly: + +.. code-block:: python + + import openstack + import openstack.config.loader + import openstack.compute.v2.server + + # Initialize and turn on debug logging + openstack.enable_logging(debug=True) + + # Initialize connection + conn = openstack.connect(cloud='mordred') + + # List the servers + for server in openstack.compute.v2.server.Server.list(session=conn.compute): + print(server.to_dict()) diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index b13a63bf4..293f027a4 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,22 +1,14 @@ -Getting started with the OpenStack SDK -====================================== +======================= +Using the OpenStack SDK +======================= + +This section of documentation pertains to those who wish to use this SDK in +their own application. If you're looking for documentation on how to contribute +to or extend the SDK, refer to the `contributor <../contributor>`_ section. For a listing of terms used throughout the SDK, including the names of projects and services supported by it, see the :doc:`glossary <../glossary>`. -Installation ------------- - -The OpenStack SDK is available on -`PyPI `_ under the name -**openstacksdk**. To install it, use ``pip``:: - - $ pip install openstacksdk - -To check the installed version you can call the module with :: - - $ python -m openstack version - .. _user_guides: User Guides @@ -29,6 +21,7 @@ approach, this is where you'll want to begin. .. toctree:: :maxdepth: 1 + Introduction Configuration Connect to an OpenStack Cloud Connect to an OpenStack Cloud Using a Config File @@ -167,7 +160,7 @@ can be customized. utils Presentations -============= +------------- .. toctree:: :maxdepth: 1