reorganize existing documentation according to the new standard layout

Move existing content around based on the doc-migration specification.

Replace :doc: markup with :ref: to have sphinx keep track of where the
files move and generate valid hyperlinks.

Add a few toctrees and index pages for the new directories.

Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454
Change-Id: I253ee8f89d3ec40e39310c18bb87ed1d3d5de330
Signed-off-by: Doug Hellmann <doug@doughellmann.com>

1 files changed, 290 insertions, 0 deletions

diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
new file mode 100644
index 00000000..d2b273d7
--- /dev/null
+++ b/doc/source/configuration/index.rst
@@ -0,0 +1,290 @@
+.. _configuration:
+
+=============
+Configuration
+=============
+
+OpenStackClient is primarily configured using command line options and environment
+variables.  Most of those settings can also be placed into a configuration file to
+simplify managing multiple cloud configurations.
+
+There is a relationship between the global options, environment variables and
+keywords used in the configuration files that should make translation between
+these three areas simple.
+
+Most global options have a corresponding environment variable that may also be
+used to set the value. If both are present, the command-line option takes priority.
+The environment variable names are derived from the option name by dropping the
+leading dashes (--), converting each embedded dash (-) to an underscore (_), and
+converting to upper case.
+
+The keyword names in the configurations files are derived from the global option
+names by dropping the ``--os-`` prefix if present.
+
+Global Options
+--------------
+
+The :ref:`openstack manpage <manpage>` lists all of the global
+options recognized by OpenStackClient and the default authentication plugins.
+
+Environment Variables
+---------------------
+
+The :ref:`openstack manpage <manpage>` also lists all of the
+environment variables recognized by OpenStackClient and the default
+authentication plugins.
+
+Configuration Files
+-------------------
+
+clouds.yaml
+~~~~~~~~~~~
+
+:file:`clouds.yaml` is a configuration file that contains everything needed
+to connect to one or more clouds.  It may contain private information and
+is generally considered private to a user.
+
+OpenStackClient looks for a file called :file:`clouds.yaml` in the following
+locations:
+
+* current directory
+* :file:`~/.config/openstack`
+* :file:`/etc/openstack`
+
+The first file found wins.
+
+The keys match the :program:`openstack` global options but without the
+``--os-`` prefix.
+
+::
+
+    clouds:
+      devstack:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: demo
+          username: demo
+          password: 0penstack
+        region_name: RegionOne
+      ds-admin:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: admin
+          username: admin
+          password: 0penstack
+        region_name: RegionOne
+      infra:
+        cloud: rackspace
+        auth:
+          project_id: 275610
+          username: openstack
+          password: xyzpdq!lazydog
+        region_name: DFW,ORD,IAD
+        interface: internal
+
+In the above example, the ``auth_url`` for the ``rackspace`` cloud is taken
+from :file:`clouds-public.yaml` (see below).
+
+The first two entries are for two of the default users of the same DevStack
+cloud.
+
+The third entry is for a Rackspace Cloud Servers account.  It is equivalent
+to the following options if the ``rackspace`` entry in :file:`clouds-public.yaml`
+(below) is present:
+
+::
+
+    --os-auth-url https://identity.api.rackspacecloud.com/v2.0/
+    --os-project-id 275610
+    --os-username openstack
+    --os-password xyzpdq!lazydog
+    --os-region-name DFW
+    --os-interface internal
+
+and can be selected on the command line::
+
+    openstack --os-cloud infra server list
+
+Note that multiple regions are listed in the ``rackspace`` entry.  An otherwise
+identical configuration is created for each region.  If ``-os-region-name`` is not
+specified on the command line, the first region in the list is used by default.
+
+The selection of ``interface`` (as seen above in the ``rackspace`` entry)
+is optional.  For this configuration to work, every service for this cloud
+instance must already be configured to support this type of interface.
+
+If you are using Identity v3 you need to specify the user and the project
+domain name as shown in the example below:
+
+::
+
+    clouds:
+      devstack:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: demo
+          username: demo
+          password: 0penstack
+          user_domain_name: Default
+          project_domain_name: Default
+        region_name: RegionOne
+
+clouds-public.yaml
+~~~~~~~~~~~~~~~~~~
+
+:file:`clouds-public.yaml` is a configuration file that is intended to contain
+public information about clouds that are common across a large number of users.
+The idea is that :file:`clouds-public.yaml` could easily be shared among users
+to simplify public cloud configuration.
+
+Similar to :file:`clouds.yaml`, OpenStackClient looks for
+:file:`clouds-public.yaml` in the following locations:
+
+* current directory
+* :file:`~/.config/openstack`
+* :file:`/etc/openstack`
+
+The first file found wins.
+
+The keys here are referenced in :file:`clouds.yaml` ``cloud`` keys.  Anything
+that appears in :file:`clouds.yaml`
+
+::
+
+    public-clouds:
+      rackspace:
+        auth:
+          auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
+
+Debugging
+~~~~~~~~~
+You may find the :ref:`configuration show <configuration-show>`
+command helpful to debug configuration issues.  It will display your current
+configuration.
+
+Logging Settings
+----------------
+
+By setting `log_level` or `log_file` in the configuration
+:file:`clouds.yaml`, a user may enable additional logging::
+
+    clouds:
+      devstack:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: demo
+          username: demo
+          password: 0penstack
+        region_name: RegionOne
+        operation_log:
+          logging: TRUE
+          file: /tmp/openstackclient_demo.log
+          level: info
+      ds-admin:
+        auth:
+          auth_url: http://192.168.122.10:35357/
+          project_name: admin
+          username: admin
+          password: 0penstack
+        region_name: RegionOne
+        log_file: /tmp/openstackclient_admin.log
+        log_level: debug
+
+:dfn:`log_file`: ``</path/file-name>``
+    Full path to logging file.
+:dfn:`log_level`: ``error`` | ``info`` | ``debug``
+    If log level is not set, ``warning`` will be used.
+
+If log level is ``info``, the following information is recorded:
+
+* cloud name
+* user name
+* project name
+* CLI start time (logging start time)
+* CLI end time
+* CLI arguments
+* CLI return value
+* and any ``info`` messages.
+
+If log level is ``debug``, the following information is recorded:
+
+* cloud name
+* user name
+* project name
+* CLI start time (logging start time)
+* CLI end time
+* CLI arguments
+* CLI return value
+* API request header/body
+* API response header/body
+* and any ``debug`` messages.
+
+When a command is executed, these logs are saved every time. Recording the user
+operations can help to identify resource changes and provide useful information
+for troubleshooting.
+
+If saving the output of a single command use the `--log-file` option instead.
+
+* `--log-file <LOG_FILE>`
+
+The logging level for `--log-file` can be set by using following options.
+
+*  `-v, --verbose`
+*  `-q, --quiet`
+*  `--debug`
+
+Locale and Language Support
+---------------------------
+
+Full support for languages is included as of OpenStackClient 3.0.0. Here are a
+few tips to ensure you have a correct configuration.
+
+Verify preferred python encoding
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Please perform the following to diagnose ensure locale settings are correct.
+Run python interactively and print the preferred encoding value, e.g.:
+
+::
+
+  $ python -c "import locale; print locale.getpreferredencoding()"
+
+If the value is ``ascii`` or ``ANSI_X3.4-1968`` or any other equivalent name for
+ASCII the problem is in your environment. You most likely do not have your LANG
+environment variable set correctly.
+
+Check the LANG environment variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``LANG`` should be of the form: `lang_code`_`[region_code]`.`encoding`.
+For example, it may look like: ``en_US.UTF-8``
+
+The critical part here is the `encoding` value of ``UTF-8``. Python will look
+up locale information and if it finds an encoding value, it will set the
+encoding property of stdin, stdout and stderr to the value found in your
+environment, if it's not defined in your environment it defaults to ASCII.
+
+Redirecting output
+~~~~~~~~~~~~~~~~~~
+
+The above only occurs if stdin, stdout and stderr are attached to a TTY. If
+redirecting data the encoding on these streams will default to the default
+encoding which is set in the `site.py` of your Python distribution, which
+defaults to ASCII. A workaround for this is to set ``PYTHONIOENCODING`` to UTF8.
+
+::
+
+  $ PYTHONIOENCODING=utf-8
+
+A final note about DevStack
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A common post devstack operation is to source the ``openrc`` file to set up
+environment variables. Doing so will unset the default ``LANG`` environment
+variable in your terminal, which will cause the preferred python encoding to
+be ``ascii``. We recommend either setting these environment variables
+independently or using the ``devstack`` or ``devstack-admin`` os-cloud profile.
+
+::
+
+  $ openstack project list --os-cloud devstack-admin