Merge ~powersj/cloud-init:docs/datasource into cloud-init:master

[Joshua Powers]

docs: cleanup output & order of datasource page

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:59c6911df9eec387113275f4b7771f579f30e606
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1129/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1129//rebuild

review: Approve (continuous-integration)

[Chad Smith (chad.smith)]

let's bring some of these home. Thanks Josh

review: Approve

diff --git a/doc/rtd/topics/datasources.rst b/doc/rtd/topics/datasources.rst
index 2148cd5..8e58be9 100644
--- a/doc/rtd/topics/datasources.rst
+++ b/doc/rtd/topics/datasources.rst
@@ -1,89 +1,57 @@
 .. _datasources:
 
-***********
 Datasources
 ***********
 
-What is a datasource?
-=====================
-
 Datasources are sources of configuration data for cloud-init that typically
-come from the user (aka userdata) or come from the stack that created the
-configuration drive (aka metadata). Typical userdata would include files,
+come from the user (e.g. userdata) or come from the cloud that created the
+configuration drive (e.g. metadata). Typical userdata would include files,
 yaml, and shell scripts while typical metadata would include server name,
-instance id, display name and other cloud specific details. Since there are
-multiple ways to provide this data (each cloud solution seems to prefer its
-own way) internally a datasource abstract class was created to allow for a
-single way to access the different cloud systems methods to provide this data
-through the typical usage of subclasses.
-
-Any metadata processed by cloud-init's datasources is persisted as
-``/run/cloud-init/instance-data.json``. Cloud-init provides tooling
-to quickly introspect some of that data. See :ref:`instance_metadata` for
-more information.
-
-
-Datasource API
---------------
-The current interface that a datasource object must provide is the following:
-
-.. sourcecode:: python
+instance id, display name and other cloud specific details.
 
-    # returns a mime multipart message that contains
-    # all the various fully-expanded components that
-    # were found from processing the raw userdata string
-    # - when filtering only the mime messages targeting
-    #   this instance id will be returned (or messages with
-    #   no instance id)
-    def get_userdata(self, apply_filter=False)
-
-    # returns the raw userdata string (or none)
-    def get_userdata_raw(self)
+Since there are multiple ways to provide this data (each cloud solution seems
+to prefer its own way) internally a datasource abstract class was created to
+allow for a single way to access the different cloud systems methods to provide
+this data through the typical usage of subclasses.
 
-    # returns a integer (or none) which can be used to identify
-    # this instance in a group of instances which are typically
-    # created from a single command, thus allowing programmatic
-    # filtering on this launch index (or other selective actions)
-    @property
-    def launch_index(self)
-
-    # the data sources' config_obj is a cloud-config formatted
-    # object that came to it from ways other than cloud-config
-    # because cloud-config content would be handled elsewhere
-    def get_config_obj(self)
-
-    #returns a list of public ssh keys
-    def get_public_ssh_keys(self)
-
-    # translates a device 'short' name into the actual physical device
-    # fully qualified name (or none if said physical device is not attached
-    # or does not exist)
-    def device_name_to_device(self, name)
+Any metadata processed by cloud-init's datasources is persisted as
+``/run/cloud-init/instance-data.json``. Cloud-init provides tooling to quickly
+introspect some of that data. See :ref:`instance_metadata` for more
+information.
 
-    # gets the locale string this instance should be applying
-    # which typically used to adjust the instances locale settings files
-    def get_locale(self)
+Known Sources
+=============
 
-    @property
-    def availability_zone(self)
+The following is a list of documents for each supported datasource:
 
-    # gets the instance id that was assigned to this instance by the
-    # cloud provider or when said instance id does not exist in the backing
-    # metadata this will return 'iid-datasource'
-    def get_instance_id(self)
+.. toctree::
+   :titlesonly:
 
-    # gets the fully qualified domain name that this host should  be using
-    # when configuring network or hostname releated settings, typically
-    # assigned either by the cloud provider or the user creating the vm
-    def get_hostname(self, fqdn=False)
+   datasources/aliyun.rst
+   datasources/altcloud.rst
+   datasources/ec2.rst
+   datasources/azure.rst
+   datasources/cloudsigma.rst
+   datasources/cloudstack.rst
+   datasources/configdrive.rst
+   datasources/digitalocean.rst
+   datasources/exoscale.rst
+   datasources/fallback.rst
+   datasources/gce.rst
+   datasources/maas.rst
+   datasources/nocloud.rst
+   datasources/opennebula.rst
+   datasources/openstack.rst
+   datasources/oracle.rst
+   datasources/ovf.rst
+   datasources/smartos.rst
 
-    def get_package_mirror_info(self)
 
+Creation
+========
 
-Adding a new Datasource
------------------------
 The datasource objects have a few touch points with cloud-init.  If you
-are interested in adding a new datasource for your cloud platform you'll
+are interested in adding a new datasource for your cloud platform you will
 need to take care of the following items:
 
 * **Identify a mechanism for positive identification of the platform**:
@@ -139,31 +107,61 @@ need to take care of the following items:
   file in ``doc/datasources/<cloudplatform>.rst``
 
 
-Datasource Documentation
-========================
-The following is a list of the implemented datasources.
-Follow for more information.
+API
+===
 
-.. toctree::
-   :maxdepth: 2
+The current interface that a datasource object must provide is the following:
 
-   datasources/aliyun.rst
-   datasources/altcloud.rst
-   datasources/azure.rst
-   datasources/cloudsigma.rst
-   datasources/cloudstack.rst
-   datasources/configdrive.rst
-   datasources/digitalocean.rst
-   datasources/ec2.rst
-   datasources/exoscale.rst
-   datasources/maas.rst
-   datasources/nocloud.rst
-   datasources/opennebula.rst
-   datasources/openstack.rst
-   datasources/oracle.rst
-   datasources/ovf.rst
-   datasources/smartos.rst
-   datasources/fallback.rst
-   datasources/gce.rst
+.. sourcecode:: python
+
+    # returns a mime multipart message that contains
+    # all the various fully-expanded components that
+    # were found from processing the raw user data string
+    # - when filtering only the mime messages targeting
+    #   this instance id will be returned (or messages with
+    #   no instance id)
+    def get_userdata(self, apply_filter=False)
+
+    # returns the raw userdata string (or none)
+    def get_userdata_raw(self)
+
+    # returns a integer (or none) which can be used to identify
+    # this instance in a group of instances which are typically
+    # created from a single command, thus allowing programmatic
+    # filtering on this launch index (or other selective actions)
+    @property
+    def launch_index(self)
+
+    # the data sources' config_obj is a cloud-config formatted
+    # object that came to it from ways other than cloud-config
+    # because cloud-config content would be handled elsewhere
+    def get_config_obj(self)
+
+    #returns a list of public ssh keys
+    def get_public_ssh_keys(self)
+
+    # translates a device 'short' name into the actual physical device
+    # fully qualified name (or none if said physical device is not attached
+    # or does not exist)
+    def device_name_to_device(self, name)
+
+    # gets the locale string this instance should be applying
+    # which typically used to adjust the instances locale settings files
+    def get_locale(self)
+
+    @property
+    def availability_zone(self)
+
+    # gets the instance id that was assigned to this instance by the
+    # cloud provider or when said instance id does not exist in the backing
+    # metadata this will return 'iid-datasource'
+    def get_instance_id(self)
+
+    # gets the fully qualified domain name that this host should  be using
+    # when configuring network or hostname related settings, typically
+    # assigned either by the cloud provider or the user creating the vm
+    def get_hostname(self, fqdn=False)
+
+    def get_package_mirror_info(self)
 
-.. vi: textwidth=78
+.. vi: textwidth=79