doc: make the RST files consistently formated and other improvements.

The biggest things here are:
 * move doc/sources/*/README.rst to doc/rtd/topics/datasources
   This gives each datasource a page in the rtd docs, which make
   it easier to read.
 * consistently use the same header style throughout.
   As suggested at
   http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
   use:
     # with overline, for parts
     * with overline, for chapters
     =, for sections
     -, for subsections
     ^, for subsubsections
     “, for paragraphs

Also, move and re-format vendor-data documentation to rtd.

1 files changed, 28 insertions, 0 deletions

diff --git a/doc/rtd/topics/datasources/openstack.rst b/doc/rtd/topics/datasources/openstack.rst
new file mode 100644
index 00000000..ea47ea85
--- /dev/null
+++ b/doc/rtd/topics/datasources/openstack.rst
@@ -0,0 +1,28 @@
+OpenStack
+=========
+
+*TODO*
+
+Vendor Data
+-----------
+
+The OpenStack metadata server can be configured to serve up vendor data
+which is available to all instances for consumption.  OpenStack vendor
+data is, generally, a JSON object.
+
+cloud-init will look for configuration in the ``cloud-init`` attribute
+of the vendor data JSON object. cloud-init processes this configuration
+using the same handlers as user data, so any formats that work for user
+data should work for vendor data.
+
+For example, configuring the following as vendor data in OpenStack would
+upgrade packages and install ``htop`` on all instances:
+
+.. sourcecode:: json
+
+  {"cloud-init": "#cloud-config\npackage_upgrade: True\npackages:\n - htop"}
+
+For more general information about how cloud-init handles vendor data,
+including how it can be disabled by users on instances, see `Vendor Data`_.
+
+.. vi: textwidth=78