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, 146 insertions, 0 deletions

diff --git a/doc/rtd/topics/datasources/opennebula.rst b/doc/rtd/topics/datasources/opennebula.rst
new file mode 100644
index 00000000..1b90a9c7
--- /dev/null
+++ b/doc/rtd/topics/datasources/opennebula.rst
@@ -0,0 +1,146 @@
+OpenNebula
+==========
+
+The `OpenNebula`_ (ON) datasource supports the contextualization disk.
+
+  See `contextualization overview`_, `contextualizing VMs`_ and
+  `network configuration`_ in the public documentation for
+  more information.
+
+OpenNebula's virtual machines are contextualized (parametrized) by
+CD-ROM image, which contains a shell script *context.sh* with
+custom variables defined on virtual machine start. There are no
+fixed contextualization variables, but the datasource accepts
+many used and recommended across the documentation.
+
+Datasource configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Datasource accepts following configuration options.
+
+::
+    
+    dsmode:
+      values: local, net, disabled
+      default: net
+
+Tells if this datasource will be processed in 'local' (pre-networking) or
+'net' (post-networking) stage or even completely 'disabled'.
+
+::
+    
+    parseuser:
+      default: nobody
+
+Unprivileged system user used for contextualization script
+processing.
+
+Contextualization disk
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following criteria are required:
+
+1. Must be formatted with `iso9660`_ filesystem
+   or have a *filesystem* label of **CONTEXT** or **CDROM**
+2. Must contain file *context.sh* with contextualization variables.
+   File is generated by OpenNebula, it has a KEY='VALUE' format and
+   can be easily read by bash 
+
+Contextualization variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are no fixed contextualization variables in OpenNebula, no standard.
+Following variables were found on various places and revisions of
+the OpenNebula documentation. Where multiple similar variables are
+specified, only first found is taken.
+
+::
+    
+    DSMODE
+
+Datasource mode configuration override. Values: local, net, disabled.
+
+::
+
+    DNS
+    ETH<x>_IP
+    ETH<x>_NETWORK
+    ETH<x>_MASK
+    ETH<x>_GATEWAY
+    ETH<x>_DOMAIN
+    ETH<x>_DNS
+
+Static `network configuration`_.
+
+::
+    
+    HOSTNAME
+
+Instance hostname.
+
+::
+    
+    PUBLIC_IP
+    IP_PUBLIC
+    ETH0_IP
+
+If no hostname has been specified, cloud-init will try to create hostname
+from instance's IP address in 'local' dsmode. In 'net' dsmode, cloud-init 
+tries to resolve one of its IP addresses to get hostname.
+
+::
+    
+    SSH_KEY
+    SSH_PUBLIC_KEY
+
+One or multiple SSH keys (separated by newlines) can be specified.
+
+::
+    
+    USER_DATA
+    USERDATA
+
+cloud-init user data.
+
+Example configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+This example cloud-init configuration (*cloud.cfg*) enables
+OpenNebula datasource only in 'net' mode.
+
+::
+    
+    disable_ec2_metadata: True
+    datasource_list: ['OpenNebula']
+    datasource:
+      OpenNebula:
+        dsmode: net
+        parseuser: nobody
+
+Example VM's context section
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+    
+    CONTEXT=[
+      PUBLIC_IP="$NIC[IP]",
+      SSH_KEY="$USER[SSH_KEY] 
+    $USER[SSH_KEY1] 
+    $USER[SSH_KEY2] ",
+      USER_DATA="#cloud-config
+    # see https://help.ubuntu.com/community/CloudInit
+    
+    packages: []
+    
+    mounts:
+    - [vdc,none,swap,sw,0,0]
+    runcmd:
+    - echo 'Instance has been configured by cloud-init.' | wall
+    " ]
+
+.. _OpenNebula: http://opennebula.org/
+.. _contextualization overview: http://opennebula.org/documentation:documentation:context_overview
+.. _contextualizing VMs: http://opennebula.org/documentation:documentation:cong
+.. _network configuration: http://opennebula.org/documentation:documentation:cong#network_configuration
+.. _iso9660: https://en.wikipedia.org/wiki/ISO_9660
+.. vi: textwidth=78