slightly rework docs

- add DeH user guides
- fix wrong menu structure
- other minor fixes

Author: gtema

doc/source/cli/index.rst

@@ -1,4 +1,8 @@
+OpenStackClient CLI Usage
+=========================
+
 .. toctree::
+   :maxdepth: 2
 
    anti_ddos.rst
    auto_scaling.rst

doc/source/contributor/index.rst

@@ -1,17 +1,10 @@
-Contributing to the OpenStack SDK
-=================================
+Contributing to the OTC Extensions
+==================================
 
 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
+development of this project. If you're looking for documentation on how to use
 the SDK to build applications, please see the `user <../user>`_ section.
 
-About the Project
------------------
-
-The OpenStack SDK is a OpenStack project aimed at providing a complete
-software development kit for the programs which make up the OpenStack
-community. It is a set of Python-based libraries, documentation, examples,
-and tools released under the Apache 2 license.
 
 Contribution Mechanics
 ----------------------
@@ -24,22 +17,15 @@ Contribution Mechanics
 Contacting the Developers
 -------------------------
 
-IRC
-***
+GitHub
+******
 
-The developers of this project are available in the
-`#openstack-sdks <http://webchat.freenode.net?channels=%23openstack-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.
+Currently no official communication other than GitHub is available
 
 Email
 *****
 
-The `openstack-dev <mailto:openstack-dev@openstack.org?subject=[sdk]%20Question%20about%20openstacksdk>`_
-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.
+???
 
 Coding Standards
 ----------------

doc/source/user/connection.rst

@@ -6,6 +6,11 @@ Connection
    -----------
    .. autofunction:: openstack.connection.from_config
 
+Registering OTC extensions
+==========================
+
+.. autofunction:: otcextensions.sdk.register_otc_extensions
+
 Connection Object
 -----------------
 

doc/source/user/guides/connect_otc.rst

@@ -0,0 +1,39 @@
+Connect OTC
+===========
+
+In order to work with an OpenStack cloud you first need to create a
+:class:`~openstack.connection.Connection` to it using your credentials. A
+:class:`~openstack.connection.Connection` can be
+created in 3 ways, using the class itself, :ref:`config-clouds-yaml`, or
+:ref:`config-environment-variables`. It is recommended to always use
+:ref:`config-clouds-yaml` as the same config can be used across tools and
+languages.
+
+Create Connection
+-----------------
+
+To create a :class:`~openstack.connection.Connection` instance, use the
+:func:`~openstack.connect` factory function.
+
+As a next step inject the OTC extensions into the retrieved connection
+
+.. code-block:: python
+
+   # An 'otc' is a cloud connection with name 'otc' configured in the clouds.yaml
+   conn = openstack.connect(cloud='otc')
+
+   # Register OTC Extensions
+   sdk.register_otc_extensions(conn)
+
+Full example at `connect_otc.py <examples/connect_otc.py>`_
+
+.. note:: To enable logging, see the :doc:`logging` user guide.
+
+Next
+----
+Now that you can create a connection, continue with the :ref:`user_guides`
+to work with an OpenStack service.
+
+.. TODO(shade) Update the text here and consolidate with the old
+   os-client-config docs so that we have a single and consistent explanation
+   of the envvars cloud, etc.

doc/source/user/guides/deh.rst

@@ -0,0 +1,73 @@
+Using OTC DeH
+=============
+
+Before working with the Dedicated Host service, you'll need to create a
+connection to your OTC cloud account by following the :doc:`connect_otc` user
+guide. This will provide you with the ``conn`` variable used in the examples
+below.
+
+.. contents:: Table of Contents
+   :local:
+
+The primary resource of the DeH service is the **host**.
+
+CRUD operations
+~~~~~~~~~~~~~~~
+
+List Hosts
+----------
+
+A **host** is a dedicated host, where virtual machines would be running.
+
+.. literalinclude:: ../examples/deh/list.py
+   :pyobject: list_hosts
+
+Full example: `deh host list`_
+
+List Hosts Types
+----------------
+
+In order to allocate a host, it's type need to be chosen first. Types might
+differ per availability zone, therefore it is required to specify in which
+AZ to look for types
+
+.. literalinclude:: ../examples/deh/list_types.py
+   :pyobject: list_host_types
+
+Full example: `deh host list type`_
+
+List Host servers
+-----------------
+
+Each DeH Host is intended to run virtual instances. Only querying list of
+servers is supported
+
+.. literalinclude:: ../examples/deh/list_servers.py
+   :pyobject: list_host_servers
+
+Full example: `deh host list server`_
+
+Provisioning operations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Provisioning actions are the main way to manipulate the hosts.
+
+Allocating a DeH Host Instance
+------------------------------
+
+A host can be allocated with a following snip.
+
+.. literalinclude:: ../examples/deh/create.py
+   :pyobject: create_host
+
+Allocating a DeH Host supports setting `quantity` parameter to allocate multiple
+hosts in a one call. Due to that the IDs of allocated hosts are being returned
+as part of the "virtual" resource in a `dedicated_host_ids` attribute
+
+Full example: `deh host create`_
+
+
+.. _deh host list: http://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list.py
+.. _deh host list type: http://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list_types.py
+.. _deh host create: http://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/create.py
+.. _deh host list server: http://github.com/opentelekomcloud/python-otcextensions/tree/master/examples/deh/list_servers.py

doc/source/user/guides/logging.rst

@@ -0,0 +1,114 @@
+=======
+Logging
+=======
+
+.. note:: TODO(shade) This document is written from a shade POV. It needs to
+          be combined with the existing logging guide, but also the logging
+          systems need to be rationalized.
+
+`openstacksdk` uses `Python Logging`_. As `openstacksdk` is a library, it does
+not configure logging handlers automatically, expecting instead for that to be
+the purview of the consuming application.
+
+Simple Usage
+------------
+
+For consumers who just want to get a basic logging setup without thinking
+about it too deeply, there is a helper method. If used, it should be called
+before any other openstacksdk functionality.
+
+.. autofunction:: openstack.enable_logging
+
+.. code-block:: python
+
+  import openstack
+  openstack.enable_logging()
+
+The ``stream`` parameter controls the stream where log message are written to.
+It defaults to `sys.stdout` which will result in log messages being written
+to STDOUT. It can be set to another output stream, or to ``None`` to disable
+logging to the console.
+
+The ``path`` parameter sets up logging to log to a file. By default, if
+``path`` is given and ``stream`` is not, logging will only go to ``path``.
+
+You can combine the ``path`` and ``stream`` parameters to log to both places
+simultaneously.
+
+To log messages to a file called ``openstack.log`` and the console on
+``stdout``:
+
+.. code-block:: python
+
+    import sys
+    import openstack
+
+    openstack.enable_logging(
+        debug=True, path='openstack.log', stream=sys.stdout)
+
+
+`openstack.enable_logging` also sets up a few other loggers and
+squelches some warnings or log messages that are otherwise uninteresting or
+unactionable by an openstacksdk user.
+
+Advanced Usage
+--------------
+
+`openstacksdk` logs to a set of different named loggers.
+
+Most of the logging is set up to log to the root ``openstack`` logger.
+There are additional sub-loggers that are used at times, primarily so that a
+user can decide to turn on or off a specific type of logging. They are listed
+below.
+
+openstack.config
+  Issues pertaining to configuration are logged to the ``openstack.config``
+  logger.
+
+openstack.task_manager
+  `openstacksdk` uses a Task Manager to perform remote calls. The
+  ``openstack.task_manager`` logger emits messages at the start and end
+  of each Task announcing what it is going to run and then what it ran and
+  how long it took. Logging ``openstack.task_manager`` is a good way to
+  get a trace of external actions `openstacksdk` is taking without full
+  `HTTP Tracing`_.
+
+openstack.iterate_timeout
+  When `openstacksdk` needs to poll a resource, it does so in a loop that waits
+  between iterations and ultimately times out. The
+  ``openstack.iterate_timeout`` logger emits messages for each iteration
+  indicating it is waiting and for how long. These can be useful to see for
+  long running tasks so that one can know things are not stuck, but can also
+  be noisy.
+
+openstack.fnmatch
+  `openstacksdk` will try to use `fnmatch`_ on given `name_or_id` arguments.
+  It's a best effort attempt, so pattern misses are logged to
+  ``openstack.fnmatch``. A user may not be intending to use an fnmatch
+  pattern - such as if they are trying to find an image named
+  ``Fedora 24 [official]``, so these messages are logged separately.
+
+.. _fnmatch: https://pymotw.com/2/fnmatch/
+
+HTTP Tracing
+------------
+
+HTTP Interactions are handled by `keystoneauth`_. If you want to enable HTTP
+tracing while using openstacksdk and are not using `openstack.enable_logging`,
+set the log level of the ``keystoneauth`` logger to ``DEBUG``.
+
+For more information see https://docs.openstack.org/keystoneauth/latest/using-sessions.html#logging
+
+.. _keystoneauth: https://docs.openstack.org/keystoneauth/latest/
+
+Python Logging
+--------------
+
+Python logging is a standard feature of Python and is documented fully in the
+Python Documentation, which varies by version of Python.
+
+For more information on Python Logging for Python v2, see
+https://docs.python.org/2/library/logging.html.
+
+For more information on Python Logging for Python v3, see
+https://docs.python.org/3/library/logging.html.

doc/source/user/index.rst

@@ -26,16 +26,14 @@ approach, this is where you'll want to begin.
 .. toctree::
    :maxdepth: 1
 
+   Plain-simple connect to OTC <guides/connect_otc>
    Configuration <config/index>
-   Connect to an OpenStack Cloud <https://docs.openstack.org/python-openstacksdk/latest/user/guides/connect>
    Connect to an OpenStack Cloud Using a Config File <https://docs.openstack.org/python-openstacksdk/latest/user/guides/connect_from_config>
-   Microversions <microversions>
    Using Cloud Abstration Layer <https://docs.openstack.org/python-openstacksdk/latest/user/usage>
-   Logging <https://docs.openstack.org/python-openstacksdk/latest/user/guides/logging>
+   Logging <guides/logging>
    Microversions <https://docs.openstack.org/python-openstacksdk/latest/user/microversions>
    Block Storage <https://docs.openstack.org/python-openstacksdk/latest/user/guides/block_storage>
    Compute <https://docs.openstack.org/python-openstacksdk/latest/user/guides/compute>
-   Database <https://docs.openstack.org/python-openstacksdk/latest/user/guides/database>
    Identity <https://docs.openstack.org/python-openstacksdk/latest/user/guides/identity>
    Image <https://docs.openstack.org/python-openstacksdk/latest/user/guides/image>
    Key Manager <https://docs.openstack.org/python-openstacksdk/latest/user/guides/key_manager>
@@ -47,6 +45,7 @@ approach, this is where you'll want to begin.
    OBS <guides/obs>
    AutoScaling <guides/auto_scaling>
    Volume Backup <guides/volume_backup>
+   Dedicated Host <guides/deh>
 
 API Documentation
 -----------------