User guide documentation for backend drivers for oslo.config

New documentation sections explaning how to use the backend
drivers for oslo.config, also include explanation on how to
use the remote_file driver.

Change-Id: I45fc2155f6fe2d8bee058dac880afba8bb9bfd53
Blueprint: oslo-config-drivers

1 files changed, 50 insertions, 17 deletions

diff --git a/oslo_config/sources/_uri.py b/oslo_config/sources/_uri.py
index 0c05726..b4d5b55 100644
--- a/oslo_config/sources/_uri.py
+++ b/oslo_config/sources/_uri.py
@@ -9,6 +9,51 @@
 # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 # License for the specific language governing permissions and limitations
 # under the License.
+r"""
+Remote File
+-----------
+
+The **remote_file** backend driver is the first driver implemented by
+oslo.config. It extends the previous limit of only accessing local files
+to a new scenario where it is possible to access configuration data over
+the network. The **remote_file** driver is based on the **requests** module
+and is capable of accessing remote files through **HTTP** or **HTTPS**.
+
+To definition of a remote_file configuration data source can be as minimal as::
+
+    [DEFAULT]
+    config_source = external_config_group
+
+    [external_config_group]
+    driver = remote_file
+    uri = http://mydomain.com/path/to/config/data.conf
+
+Or as complete as::
+
+    [DEFAULT]
+    config_source = external_config_group
+
+    [external_config_group]
+    driver = remote_file
+    uri = https://mydomain.com/path/to/config/data.conf
+    ca_path = /path/to/server/ca.pem
+    client_key = /path/to/my/key.pem
+    client_cert = /path/to/my/cert.pem
+
+On the following sessions, you can find more information about this driver's
+classes and its options.
+
+The Driver Class
+================
+
+.. autoclass:: URIConfigurationSourceDriver
+
+The Configuration Source Class
+==============================
+
+.. autoclass:: URIConfigurationSource
+
+"""
 
 import requests
 import tempfile
@@ -18,7 +63,7 @@ from oslo_config import sources
 
 
 class URIConfigurationSourceDriver(sources.ConfigurationSourceDriver):
-    """A configuration source driver for remote files served through http[s].
+    """A backend driver for remote files served through http[s].
 
     Required options:
       - uri: URI containing the file location.
@@ -80,17 +125,17 @@ class URIConfigurationSourceDriver(sources.ConfigurationSourceDriver):
 class URIConfigurationSource(sources.ConfigurationSource):
     """A configuration source for remote files served through http[s].
 
-    :uri: The Uniform Resource Identifier of the configuration to be
+    :param uri: The Uniform Resource Identifier of the configuration to be
           retrieved.
 
-    :ca_path: The path to a CA_BUNDLE file or directory with
+    :param ca_path: The path to a CA_BUNDLE file or directory with
               certificates of trusted CAs.
 
-    :client_cert: Client side certificate, as a single file path
+    :param client_cert: Client side certificate, as a single file path
                   containing either the certificate only or the
                   private key and the certificate.
 
-    :client_key: Client side private key, in case client_cert is
+    :param client_key: Client side private key, in case client_cert is
                  specified but does not includes the private key.
     """
 
@@ -117,18 +162,6 @@ class URIConfigurationSource(sources.ConfigurationSource):
             return response.text
 
     def get(self, group_name, option_name, opt):
-        """Return the value of the option from the group.
-
-        :param group_name: Name of the group.
-        :type group_name: str
-        :param option_name: Name of the option.
-        :type option_name: str
-        :param opt: The option definition.
-        :type opt: Opt
-        :returns: A tuple (value, location) where value is the option value
-                  or oslo_config.sources._NoValue if the (group, option) is
-                  not present in the source, and location is a LocationInfo.
-        """
         try:
             return self._namespace._get_value(
                 [(group_name, option_name)],