Refresh README.rst, expand usage.rst

As part of an effort to fully document os-net-config, this change
makes the README.rst more consistent with other projects, and expands
the usage.rst page to describe useful command-line arguments.

Now that the README has a link to the generated documentation[1], the
provider section can be replaced by the one in the usage.rst page.

[1] https://docs.openstack.org/os-net-config/latest/

Change-Id: I065da7c7028bf081fb1d87ef64c4f3f873bfe111

README.rst

@@ -1,30 +1,25 @@
-========================
-Team and repository tags
-========================
-
-.. image:: https://governance.openstack.org/tc/badges/os-net-config.svg
-    :target: https://governance.openstack.org/tc/reference/tags/index.html
-
-.. Change things from this point on
-
 =============
 os-net-config
 =============
 
-host network configuration tool
+Team and repository tags
+------------------------
 
-An implementation of the 'network configuration' spec @
-https://review.opendev.org/#/c/97859/.
-The intention is for this code to be moved under the tripleo project in due course.
+.. image:: https://governance.openstack.org/tc/badges/os-net-config.svg
+    :target: https://governance.openstack.org/tc/reference/tags/index.html
 
-* Free software: Apache License (2.0)
+Overview
+--------
+
+``os-net-config`` is a host network configuration tool which supports multiple
+backend configuration providers.
+
+* Documentation: https://docs.openstack.org/os-net-config/latest
 * Source: https://opendev.org/openstack/os-net-config
 * Bugs: https://bugs.launchpad.net/os-net-config
+* Release Notes: https://docs.openstack.org/releasenotes/os-net-config
+* Free software: Apache License (2.0)
 
-Release Notes
--------------
-
-* https://docs.openstack.org/releasenotes/os-net-config
 
 Features
 --------
@@ -104,24 +99,4 @@ YAML Config Examples
             addresses:
               - 
                 ip_netmask: 192.0.2.1/24
-  
-  ..
-
-Provider Configuration
-----------------------
-Providers are use to apply (implement) the desired configuration on the
-host system. By default 3 providers are implemented:
-
-* Ifcfg: persistent network config format stored in
-  /etc/sysconfig/network-scripts
-
-* ENI: persistent network config format stored in /etc/network/interfaces
-
-* iproute2: non-persistent provider which implements the config using
-  iproute2, vconfig, etc... (implementation in progress)
-
-When using bin/os-net-config the provider is automatically selected based on
-the host systems perferred persistent network type (ifcfg or ENI). This can
-be customized via the `--provider` CLI option.
-
-
+                

doc/source/usage.rst

@@ -1,6 +1,79 @@
-========
+=====
 Usage
-========
+=====
+
+Backend Provider Detection
+--------------------------
+
+The ``--provider`` argument to ``os-net-config`` selects one of the available
+backend providers:
+
+- ``ifcfg`` Configure network interfaces using the ifcfg format
+  ``/etc/sysconfig/network-scripts/`` files.
+- ``eni`` Configure network interfaces using the Debian/Ubuntu
+  ``/etc/network/interfaces`` format
+- ``iproute`` (Not implemented)
+
+When the ``--provider`` argument is not specified when calling
+``os-net-config`` the provider will be chosen using the following rules:
+
+1) If path ``/etc/sysconfig/network-scripts/`` exists, use the ``ifcfg``
+   provider.
+
+2) Otherwise if path ``/etc/network/`` exists, use the ``eni`` provider.
+
+In these rules, if a path is specified for ``--root-dir`` this will be
+prepended to the checked paths before doing the above tests.
+
+Interface Mapping
+-----------------
+
+The file ``/etc/os-net-config/mapping.yaml`` can contain mappings from
+interface identifiers to the actual interface names. A different mapping file can
+be used by using the ``--mapping-file`` argument to ``os-net-config``.
+
+This mapping allows consistent interface identifiers to be used in the config
+without needing the full interface name which can vary across servers and
+hardware changes. This also allows config to be performed for interfaces
+which are in a ``DOWN`` state before configuration.
+
+The format of the mapping.yaml is as follows:
+
+  .. code-block:: yaml
+
+    interface_mapping:
+      nic1: enp0s20f0u2u1u2
+      nic2: enp0s31f6
+
+To assist in writing this file, the following command will generate a JSON
+snippet with discovered interfaces::
+
+    $ os-net-config --interfaces
+    {'nic1': 'enp0s20f0u2u1u2', 'nic2': 'enp0s31f6'}
+
+When the ``--persist-mapping`` argument is specified when calling
+``os-net-config`` then the existing interfaces names will be permanently
+renamed to their identifier name.
+
+Network Configuration
+---------------------
+
+By default the file ``/etc/os-net-config/config.yaml`` will be sourced for
+the network configuration, but an alternate file can be used with the
+``--config-file`` argument. The following arguments change the behaviour
+during configuration:
+
+- ``--detailed-exit-codes`` If enabled an exit code of ``2`` means that
+  files were modified.
+- ``--exit-on-validation-errors`` Exit with an error if configuration
+  file validation fails.
+- ``--noop`` Return the configuration commands, without applying them.
+- ``--no-activate`` Install the configuration but don't start/stop
+  interfaces.
+- ``--cleanup`` Cleanup unconfigured interfaces.
+
+Python Library
+--------------
 
 To use os-net-config in a project::