Warn that keystone CLI is pending deprecation

The keystone CLI is pending deprecation so warn about it in the
developer docs.

DocImpact

Change-Id: Ibca9d4cd8d31a62ee1ec7f24671c8f0f01ca9f7f
Rename the client API docs

Since developers want to use the APIs, the docs should be more
enticing and say that it describes how to use the APIs.

Also, called it "V3 Client API" since this reads better than
"Client V3 API" and it matches the order in the module path.

Change-Id: I79dd6f6891bf48b477b35157256a0219426d171c
Docstring cleanup for return type

The :returns: directive doesn't take an argument. To specify the
return type, use the :rtype: directive.

Change-Id: I3aaab824792333b3f75a10af92f5b712cc9b4ff6
Remove middleware architecture doc

The auth_token middleware was moved to the keystonemiddleware repo and
the middleware architecture doc was copied there. The copy in the
client repo can be removed.

Change-Id: Ic7b7f970a08746dd4f5d61dd5144c1dae168ad6d
Make keystoneclient use an adapter

Apart from making keystoneclient follow the same patterns of using an
adapter that we are trying to push onto other clients this severs the
cyclical dependency between managers and the client object.

There are a few changes that have had to be rolled into one to make the
transition work. These can't be separated unfortunately as they are
interdependent.

* managers are now passed the adapter instead of the client. They
  therefore don't have reference to the other managers on the client.
* The adapter has been subclassed to provide user_id as there are some
  managers that require user_id be provided for changing passwords etc.
* client.auth_url has been replaced with a call to get_endpoint which is
  supported by the adapter.
* management=True has been removed from all the managers and they now
  correctly set the interface they want.

Change-Id: I49fbd50571f0c1484e1cbc3dcb2159d25b21b1bc
Cleanup exception logging

LOG.exception() already prints the exception, so passing the
exception to it isn't useful. Pass a message instead.

Change-Id: If5b5be1e275a4688a04ba4ccc582149a3a5f2bd2
Curl statements to include globoff for IPv6 URLs

python-keystoneclient displays curl statements for debugging/troubleshooting
purposes. For IPv6 URLs, curl requires --globoff to be passed in the
arguments. Since keystoneclient does not use curl directly, this patch
displays the curl commands with globoff option which works for both
IPv4 and IPv6 URLs.
Fix adapted from python-novaclient Ib7099e8e3bbc15f29bbaa1db37ef21e78a74e7bc

Closes-Bug: #1228744
Change-Id: Ia05e622dea653597d412ffe0987077616fbb18af
Replace magic numbers with named symbols

Magic numbers were used for the return codes from the openssl
command. These are replaced with named symbols for readability.

Change-Id: I01a77927bd577bcf81b728a1df23c2058c1a9ae3
Merge "Curl statements to include globoff for IPv6 URLs"
Merge "Replace magic numbers with named symbols"
Merge "Remove middleware architecture doc"
Merge "Cleanup exception logging"
Merge "Warn that keystone CLI is pending deprecation"
Merge "Rename the client API docs"
Merge "Docstring cleanup for return type"
Merge "Make keystoneclient use an adapter"