Update README

Restructure things to be a little more helpful. Also add a reference to
the Dockerfile we provide and remove an errant header that should have
been removed in change Ife108e6ae191641b56e872e4616a3f4ec78281e8.

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

README.rst

@@ -1,7 +1,3 @@
-========================
-Team and repository tags
-========================
-
 ===============
 OpenStackClient
 ===============
@@ -10,94 +6,158 @@ OpenStackClient
     :target: https://pypi.org/project/python-openstackclient/
     :alt: Latest Version
 
-OpenStackClient (aka OSC) is a command-line client for OpenStack that brings
+OpenStackClient (OSC) is a command-line client for OpenStack that brings
 the command set for Compute, Identity, Image, Network, Object Store and Block
 Storage APIs together in a single shell with a uniform command structure.
+Support for additional service APIs is provided via plugins.
 
 The primary goal is to provide a unified shell command structure and a common
 language to describe operations in OpenStack.
 
-* `PyPi`_ - package installation
-* `Online Documentation`_
-* `Launchpad project`_ - bugs and feature requests
-* `Blueprints`_ - feature specifications (historical only)
-* `Source`_
-* `Developer`_ - getting started as a developer
-* `Contributing`_ - contributing code
-* `Testing`_ - testing code
-* IRC: #openstack-sdks on OFTC (irc.oftc.net)
-* License: Apache 2.0
-
-.. _PyPi: https://pypi.org/project/python-openstackclient
-.. _Online Documentation: https://docs.openstack.org/python-openstackclient/latest/
-.. _Blueprints: https://blueprints.launchpad.net/python-openstackclient
-.. _`Launchpad project`: https://bugs.launchpad.net/python-openstackclient
-.. _Source: https://opendev.org/openstack/python-openstackclient
-.. _Developer: https://docs.openstack.org/project-team-guide/project-setup/python.html
-.. _Contributing: https://docs.openstack.org/infra/manual/developers.html
-.. _Testing: https://docs.openstack.org/python-openstackclient/latest/contributor/developing.html#testing
-.. _Release Notes: https://docs.openstack.org/releasenotes/python-openstackclient
-
 Getting Started
 ===============
 
-OpenStack Client can be installed from PyPI using pip::
+OpenStack Client can be installed from PyPI using pip:
+
+.. code-block:: shell
 
     python3 -m pip install python-openstackclient
 
-There are a few variants on getting help.  A list of global options and supported
+You can use ``--help`` or the ``help`` command to get a list of global options
-commands is shown with ``--help``::
+and supported commands:
+
+.. code-block:: shell
 
     openstack --help
-
-There is also a ``help`` command that can be used to get help text for a specific
-command::
-
     openstack help
+
+You can also get help for a specific command:
+
+.. code-block:: shell
+
+    openstack server create --help
     openstack help server create
 
-If you want to make changes to the OpenStackClient for testing and contribution,
+You can add support for additional services by installing their clients. For
-make any changes and then run::
+example, to add support for the DNS service (designate):
+
+.. code-block:: shell
+
+    python3 -m pip install python3-designateclient
+
+A ``Dockerfile`` is provided for your convenience in the repository. You can
+use this to build your own container images:
+
+.. code-block:: shell
 
     git clone https://opendev.org/openstack/python-openstackclient
     cd python-openstackclient
-    python3 -m pip install -e .
+    podman build . -t example.com/myuser/openstackclient
+
+For more information the available options and commands, refer to the `Users
+Guide`__.
+
+.. __: https://docs.openstack.org/python-openstackclient/latest/cli/index.html
 
 Configuration
 =============
 
-The CLI is configured via environment variables and command-line
+OpenStack Client must be configured with authentication information in order to
-options as listed in  https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html.
+communicate with a given OpenStack cloud. This configuration can be achieved
+via a ``clouds.yaml`` file, a set of environment variables (often shared via an
+``openrc`` file), a set of command-line options, or a combination of all three.
+Your cloud provider or deployment tooling will typically provide either a
+``clouds.yaml`` file or ``openrc`` file for you. If using a ``clouds.yaml``
+file, OpenStack Client expects to find it in one of the following locations:
 
-Authentication using username/password is most commonly used:
+* If set, the path indicated by the ``OS_CLIENT_CONFIG_FILE`` environment
+  variable
+* ``.`` (the current directory)
+* ``$HOME/.config/openstack``
+* ``/etc/openstack``
 
-- For a local user, your configuration will look like the one below::
+The options you should set will depend on the configuration of your cloud and
+the authentication mechanism(s) supported. For example, consider a cloud that
+supports username/password authentication. Configuration for this cloud using a
+``clouds.yaml`` file would look like so:
+
+.. code-block:: yaml
+
+    clouds:
+      my-cloud:
+        auth:
+          auth_url: '<url-to-openstack-identity>'
+          project_name: '<project-name>'
+          project_domain_name: '<project-domain-name>'
+          username: '<username>'
+          user_domain_name: '<user-domain-name>'
+          password: '<password>'  # (optional)
+        region_name: '<region>'
+
+The corresponding environment variables would look very similar:
+
+.. code-block:: shell
 
     export OS_AUTH_URL=<url-to-openstack-identity>
-    export OS_IDENTITY_API_VERSION=3
+    export OS_REGION_NAME=<region>
     export OS_PROJECT_NAME=<project-name>
     export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
     export OS_USERNAME=<username>
     export OS_USER_DOMAIN_NAME=<user-domain-name>
     export OS_PASSWORD=<password>  # (optional)
 
-  The corresponding command-line options look very similar::
+Likewise, the corresponding command-line options would look very similar:
 
-    --os-auth-url <url>
+::
-    --os-identity-api-version 3
+
+    openstack
+    --os-auth-url <url-to-openstack-identity>
+    --os-region <region>
     --os-project-name <project-name>
     --os-project-domain-name <project-domain-name>
     --os-username <username>
     --os-user-domain-name <user-domain-name>
     [--os-password <password>]
 
-- For a federated user, your configuration will look the so::
+.. note::
+
+    If a password is not provided above (in plaintext), you will be
+    interactively prompted to provide one securely.
+
+Some clouds use federated authentication. If this is the case, your
+configuration will be slightly more involved. For example, to configure
+username/password authentication for a federated user using a ``clouds.yaml``
+file:
+
+.. code-block:: yaml
+
+    clouds:
+      my-cloud:
+        auth:
+          auth_url: '<url-to-openstack-identity>'
+          project_name: '<project-name>'
+          project_domain_name: '<project-domain-name>'
+          username: '<username-in-idp>'
+          user_domain_name: '<user-domain-name>'
+          password: '<password-in-idp>'
+          identity_provider: '<the-desired-idp-in-keystone>'
+          client_id: '<the-client-id-configured-in-the-idp>'
+          client_secret: '<the-client-secret-configured-in-the-idp>'
+          openid_scope: '<the-scopes-of-desired-attributes-to-claim-from-idp>'
+          protocol: '<the-protocol-used-in-the-apache2-oidc-proxy>'
+          access_token_type: '<the-access-token-type-used-by-your-idp>'
+          discovery_endpoint: '<the-well-known-endpoint-of-the-idp>'
+        auth_type: 'v3oidcpassword'
+        region_name: '<region>'
+
+The corresponding environment variables would look very similar:
+
+.. code-block:: shell
 
     export OS_PROJECT_NAME=<project-name>
     export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
     export OS_AUTH_URL=<url-to-openstack-identity>
     export OS_IDENTITY_API_VERSION=3
-    export OS_AUTH_PLUGIN=openid
     export OS_AUTH_TYPE=v3oidcpassword
     export OS_USERNAME=<username-in-idp>
     export OS_PASSWORD=<password-in-idp>
@@ -109,7 +169,9 @@ Authentication using username/password is most commonly used:
     export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
     export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
 
-  The corresponding command-line options look very similar::
+Likewise, the corresponding command-line options would look very similar:
+
+.. code-block:: shell
 
     --os-project-name <project-name>
     --os-project-domain-name <project-domain-name>
@@ -127,5 +189,41 @@ Authentication using username/password is most commonly used:
     --os-access-token-type <the-access-token-type-used-by-your-idp>
     --os-discovery-endpoint <the-well-known-endpoint-of-the-idp>
 
-If a password is not provided above (in plaintext), you will be interactively
+For more information on configuring authentication, including an overview of
-prompted to provide one securely.
+the many authentication mechanisms supported, refer to the `Authentication
+guide`__. For more information on configuration in general, refer to the
+`Configuration guide`__.
+
+.. __: https://docs.openstack.org/python-openstackclient/latest/cli/authentication.html.
+.. __: https://docs.openstack.org/python-openstackclient/latest/configuration/index.html
+
+Contributing
+============
+
+You can clone the repository from opendev.org::
+
+    git clone https://opendev.org/openstack/python-openstackclient
+    cd python-openstackclient
+
+OpenStack Client uses the same contributor process as other OpenStack projects.
+For information on this process, including help on setting up you Gerrit
+account and an overview of the CI process, refer to the `OpenStack Contributors
+Guide`__.
+
+For more information on contributing to OpenStack Client itself, including
+guidance on how to design new commands and how to report bugs, refer to the
+`Contributors Guide`__.
+
+.. __: https://docs.openstack.org/python-openstackclient/latest/contributor/index.html
+.. __: https://docs.opendev.org/opendev/infra-manual/latest/developers.html
+
+Links
+-----
+
+* `Issue Tracker <https://bugs.launchpad.net/python-openstackclient>`_
+* `Code Review <https://review.opendev.org/#/q/status:open+project:openstack/openstacksdk,n,z>`_
+* `Documentation <https://docs.openstack.org/python-openstackclient/latest/>`_
+* `PyPi <https://pypi.org/project/python-openstackclient>`_
+* `Mailing list <https://lists.openstack.org/mailman3/lists/openstack-discuss.lists.openstack.org/>`_
+* `Release Notes <https://docs.openstack.org/releasenotes/python-openstackclient>`_
+* `IRC (#openstack-sdks on OFTC (irc.oftc.net)) <irc://irc.oftc.net/openstack-sdks>`_