Update documentation

Slight update to make it hopefuly a little bit clearer.

Include the README as the top-level document.  Remove the unused other
files, but keep a link to CONTRIBUTING.

Move some of the details into a "systemd" subsection to make the
different paths a bit clearer.

Change-Id: I0f5335611255bf6873d03bdbbc5d6c9d7ec5a6d4

README.rst

@@ -17,23 +17,42 @@ configuration drive.
 What does glean do?
 -------------------
 
-Glean firstly checks for configuration drive based information and, if
+Broadly, glean checks for configuration drive based information and,
-found, uses that for network configuration.  If config-drive is not
+if found, uses that to configure the network.  If config-drive is not
-found, it falls back to configuring any available interfaces with DHCP.
+found, it falls back to configuring any available interfaces with
+DHCP.
 
 Specifically, it will mount the special block-device with label
 `config-2` and parse the `network_info.json` and `vendor_info.json`
 files within.  If appropriate network configuration is found, it will
-write out network configuration files (e.g. `/etc/sysconfig/network/`
+write out network configuration files.
-scripts on Red Hat platforms, `/etc/interfaces` on Debian, etc).
 
-If no network info is found there, available interfaces will be probed
+If no network info is found there, available interfaces can be probed
 from `/sys/class/net` and any that appear to be up will be configured
 for use with DHCP.
 
 It will also handle `authorized_keys` and host-name info provided from
 `meta_data.json`.
 
+How does glean do this?
++++++++++++++++++++++++
+
+systemd environment
+===================
+
+glean install will add a `udev` rules file (`99-glean.rules`) that
+triggers on any network device being added.  This will run the
+`glean@.service` systemd template for the interface specified.
+
+This systemd unit firstly determines if there is already a
+`/etc/sysconfig/network/` configuration for the interface; if so, the
+interface is considered configured and skipped.
+
+If not, glean is started with the interface specified.  The
+configuration drive is probed to see if network configuration for the
+interface is available.  If so, it will be added, otherwise the
+interface will configured for DHCP.
+
 How do I use glean?
 -------------------
 
@@ -42,8 +61,8 @@ system startup environment.  It should handle `sysv`, `upstart` and
 `systemd` to cover all major distributions.  This should be run once,
 during install or image build.
 
-The startup environment will run `glean.sh`, which configures any
+The startup environment will be modified as described above to
-found interfaces as described above.
+configure any found interfaces.
 
 Differences to cloud-config?
 ----------------------------

doc/source/index.rst

@@ -3,22 +3,12 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to glean's documentation!
+.. include:: ../../README.rst
-========================================================
 
-Contents:
+More information
+================
 
 .. toctree::
    :maxdepth: 2
 
-   readme
-   installation
-   usage
    contributing
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

doc/source/installation.rst

@@ -1,12 +0,0 @@
-============
-Installation
-============
-
-At the command line::
-
-    $ pip install glean
-
-Or, if you have virtualenvwrapper installed::
-
-    $ mkvirtualenv glean
-    $ pip install glean

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

doc/source/usage.rst

@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use glean in a project::
-
-    import glean