docs: Add intro doc to user guide

This is essentially a repeat of content from the recently updated
README. We simply duplicate it rather than using complicated includes
because $effort.

Change-Id: If41a6b2d43d00e5bd78f6b2bd5bf33fa4a5d38d5
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

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
+The developers of this project are available in the `#openstack-sdks`__ channel
-`#openstack-sdks <http://webchat.freenode.net?channels=%23openstack-sdks>`_
+on Freenode. This channel includes conversation on SDKs and tools within the
-channel on Freenode. This channel includes conversation on SDKs and tools
+general OpenStack community, including OpenStackClient as well as occasional
-within the general OpenStack community, including OpenStackClient as well
+talk about SDKs created for languages outside of Python.
-as occasional talk about SDKs created for languages outside of Python.
+
+.. __: http://webchat.freenode.net?channels=%23openstack-sdks
 
 Email
-*****
+~~~~~
 
-The `openstack-discuss <mailto:openstack-discuss@openstack.org?subject=[sdk]%20Question%20about%20openstacksdk>`_
+The `openstack-discuss`__ mailing list fields questions of all types on
-mailing list fields questions of all types on OpenStack. Using the
+OpenStack. Using the ``[sdk]`` filter to begin your email subject will ensure
-``[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
 ----------------
 

doc/source/index.rst

@@ -1,12 +1,13 @@
-Welcome to the OpenStack SDK!
+============
-=============================
+openstacksdk
+============
 
 This documentation is split into three sections:
 
-* an :doc:`installation <install/index>` guide
+* An :doc:`installation <install/index>` guide
-* a section for :doc:`users <user/index>` looking to build applications
+* A section for :doc:`users <user/index>` looking to build applications
   which make use of OpenStack
-* a section for those looking to :doc:`contribute <contributor/index>`
+* A section for those looking to :doc:`contribute <contributor/index>`
   to this project
 
 Installation
@@ -33,8 +34,6 @@ For Contributors
 
    contributor/index
 
-.. include:: ../../README.rst
-
 General Information
 -------------------
 

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
+To check the installed version you can call the module with:
-    $ pip install openstacksdk
+
+.. code-block:: bash
+
+   $ python -m openstack version
+
+.. __: https://pypi.org/project/openstacksdk

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
+* ``.`` (the current directory)
-* ~/.config/openstack
+* ``$HOME/.config/openstack``
-* /etc/openstack
+* ``/etc/openstack``
 
 The first file found wins.
 

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())

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 <https://pypi.org/project/openstacksdk>`_ 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 <guides/intro>
    Configuration <config/index>
    Connect to an OpenStack Cloud <guides/connect>
    Connect to an OpenStack Cloud Using a Config File <guides/connect_from_config>
@@ -167,7 +160,7 @@ can be customized.
    utils
 
 Presentations
-=============
+-------------
 
 .. toctree::
    :maxdepth: 1