Improve README to follow our template

Func-Test-PR: https://github.com/openstack-charmers/zaza-openstack-tests/pull/376
Change-Id: I8952ffc0ad05987d1ea73ff7e2e16c4054939e68

README.md

@@ -1,33 +0,0 @@
-# Overview
-
-This is a "source" charm, which is intended to be strictly the top
-layer of a built charm.  This structure declares that any included
-layer assets are not intended to be consumed as a layer from a
-functional or design standpoint.
-
-# Test and Build
-
-Building, pushing and publishing to the charm store is automated
-by CI to ensure consistent flow.  Manually building is useful for
-development and testing, however.
-
-```
-tox -e pep8
-tox -e py3
-tox -e build
-cd build/builds/neutron-api-plugin-arista
-
-# Set one of these env vars, depending on whether you want to
-# download the Arista image from a remote place or have it already
-# locally:
-export TEST_ARISTA_IMAGE_REMOTE=http://example.com/swift/v1/images/arista-cvx-virt-test.qcow2
-export TEST_ARISTA_IMAGE_LOCAL=/tmp/arista-cvx-virt-test.qcow2
-
-tox -e func
-```
-
-# Bugs
-
-Please report bugs on [Launchpad](https://bugs.launchpad.net/charm-neutron-api-plugin-arista/+filebug).
-
-For general questions please refer to the OpenStack [Charm Guide](https://docs.openstack.org/charm-guide/latest/).

README.md

@@ -0,0 +1 @@
+src/README.md

docs/upgrading-to-stable.md

@@ -52,6 +52,7 @@ applications:
     options:
       manage-neutron-plugin-legacy-mode: False
       # No need for `enable-arista` anymore
+      [...]
 
   neutron-api-plugin-arista:
     charm: cs:~openstack-charmers-next/neutron-api-plugin-arista-2

src/README.md

@@ -1,28 +1,68 @@
 # Overview
 
-This subordinate charm provides the Arista ML2 Plugin support to the OpenStack
+This subordinate charm provides the
-Neutron API service.
+[Arista ML2 Plugin][python-networking-arista] support to the
+[OpenStack Neutron API service][charm-neutron-api].
 
-When this charm is related to the neutron-api charm it will install the
+> **Notes**:
-Arista Neutron packages on each neutron-api unit in the region and supply the
+> * For now the neutron-api-plugin-arista charm is only supported up to
-desired configuration to the neutron-api service.
+>   OpenStack Queens.
+> * For upgrading from earlier prototypes of this charm see
+>   [Upgrading to stable charm][upgrading-to-stable].
+
+When this charm is related to the neutron-api charm it will install the Arista
+Neutron packages on each neutron-api unit in the region and supply the desired
+configuration to the neutron-api service.
 
 # Usage
 
+## Configuration
+
+This section covers common and/or important configuration options. See file
+`config.yaml` for the full list of options, along with their descriptions and
+default values. See the [Juju documentation][juju-docs-config-apps] for details
+on configuring applications.
+
+#### `eapi-host`
+
+The `eapi-host` option is the IP address serving the Arista API (a.k.a. eAPI)
+from the charm's perspective.
+
+#### `eapi-username`
+
+The `eapi-username` option is the username to be used for authenticating to the
+Arista API.
+
+#### `eapi-password`
+
+The `eapi-password` option is the password to be used for authenticating to the
+Arista API.
+
+## Deployment
+
+Because this is a subordinate charm a relation will need to be added to another
+application to have the charm deployed on a machine.
+
 To deploy (partial deployment only):
 
     juju deploy neutron-api
     juju deploy neutron-openvswitch
-    juju deploy neutron-api-plugin-arista
+    juju deploy neutron-api-plugin-arista --config eapi-host=...
 
     juju add-relation neutron-api neutron-api-plugin-arista
-    juju add-relation neutron-api mysql
-    juju add-relation neutron-api rabbitmq-server
     juju add-relation neutron-api neutron-openvswitch
-    juju add-relation neutron-api nova-cloud-controller
 
 # Bugs
 
-Please report bugs on [Launchpad](https://bugs.launchpad.net/charm-neutron-api-plugin-arista/+filebug).
+Please report bugs on [Launchpad][lp-bugs-neutron-arista].
 
-For general questions please refer to the OpenStack [Charm Guide](https://docs.openstack.org/charm-guide/latest/).
+For general questions please refer to the [OpenStack Charm Guide][cg].
+
+<!-- LINKS -->
+
+[charm-neutron-api]: https://jaas.ai/neutron-api
+[cg]: https://docs.openstack.org/charm-guide
+[python-networking-arista]: https://opendev.org/x/networking-arista
+[lp-bugs-neutron-arista]: https://bugs.launchpad.net/charm-neutron-api-plugin-arista/+filebug
+[juju-docs-config-apps]: https://juju.is/docs/configuring-applications
+[upgrading-to-stable]: https://github.com/openstack/charm-neutron-api-plugin-arista/blob/master/docs/upgrading-to-stable.md