Formatting and content updates for README.md

- Consistent use of Markdown headings: children of an h1 heading should be
  h2 headings
- Consistent line wrapping: previously, some paragraphs were line-wrapped
  and others were not. This commit makes all paragraphs unwrapped.
- Use `pip` for installation rather than `python setup.py`
- Make it easier to copy-and-paste most command examples by removing `$`
  shell prompts
- Remove unnecessary `GRANT` commands from mysql instructions: `%` is a wildcard so 'esi_leap'@'%'` already grants access to `'esi_leap'@'<database_ip>'`
- Simplify the "Container Installation" section

README.md

@@ -1,68 +1,54 @@
 # esi-leap
 
-esi-leap is an OpenStack service for leasing baremetal nodes, designed to run
-on top of [multi-tenant
-Ironic](https://docs.openstack.org/ironic/latest/admin/node-multitenancy.html).
-It consists of an API that provides endpoints for leasing operations and a
-manager service that updates the status of leases and offers as required. See
-the [documentation](https://esi.readthedocs.io/en/latest/index.html) for
-more info on ESI.
+esi-leap is an OpenStack service for leasing baremetal nodes, designed to run on top of [multi-tenant Ironic](https://docs.openstack.org/ironic/latest/admin/node-multitenancy.html). It consists of an API that provides endpoints for leasing operations and a manager service that updates the status of leases and offers as required. See the [documentation](https://esi.readthedocs.io/en/latest/index.html) for more info on ESI.
 
-
-### Installation
+## Installation
 
 To install as a package:
- - `pip install esi-leap`
-
-To install from source:
 
 ```
-    $ git clone https://github.com/CCI-MOC/esi-leap
-    $ cd esi-leap
-    $ sudo python setup.py install
+pip install esi-leap
 ```
 
+To install from source:
 
-### Client
+```
+git clone https://github.com/CCI-MOC/esi-leap
+cd esi-leap
+pip install .
+```
 
-esi-leap has a command line client which can be found here:
-https://github.com/CCI-MOC/python-esileapclient
+## Client
 
+esi-leap has a command line client which can be found here: https://github.com/CCI-MOC/python-esileapclient
 
-### Create the esi-leap Database
+## Create the esi-leap Database
 
-The esi-leap service requires a database to store its information. To set this
-up using the MySQL database used by other OpenStack services, run the following
-commands, replacing \<PASSWORD\> with a suitable password and \<DATABASE\_IP\>
-with the IP address of your MySQL database (if you're not sure, use localhost
-or 127.0.0.1).
+The esi-leap service requires a database to store its information. To set this up using the MySQL database used by other OpenStack services, run the following commands, replacing `<PASSWORD>` with a suitable password and `<DATABASE_IP>` with the IP address of your MySQL database (if you're not sure, use `localhost` or `127.0.0.1`).
 
 ```
-    $ mysql -u root -p
-    mysql> CREATE USER 'esi_leap'@'<DATABASE_IP>' IDENTIFIED BY '<PASSWORD>';
-    mysql> CREATE USER 'esi_leap'@'%' IDENTIFIED BY '<PASSWORD>';
-    mysql> CREATE DATABASE esi_leap CHARACTER SET utf8;
-    mysql> GRANT ALL PRIVILEGES ON esi_leap.* TO 'esi_leap'@'<DATABASE_IP>';
-    mysql> GRANT ALL PRIVILEGES ON esi_leap.* TO 'esi_leap'@'%';
-    mysql> FLUSH PRIVILEGES;
+$ mysql -u root -p
+mysql> CREATE USER 'esi_leap'@'%' IDENTIFIED BY '<PASSWORD>';
+mysql> CREATE DATABASE esi_leap CHARACTER SET utf8;
+mysql> GRANT ALL PRIVILEGES ON esi_leap.* TO 'esi_leap'@'%';
+mysql> FLUSH PRIVILEGES;
 ```
 
 If you use this method, the resulting database connection string should be:
 
 ```
-    mysql+pymysql://esi_leap:PASSWORD@DATABASE_IP/esi_leap
+mysql+pymysql://esi_leap:PASSWORD@DATABASE_IP/esi_leap
 ```
 
-
-### Configuration
+## Configuration
 
 Run the following commands to generate the configuration file and copy it to
 the right place:
 
 ```
-    $ tox -egenconfig
-    $ sudo mkdir /etc/esi-leap
-    $ sudo cp etc/esi-leap/esi-leap.conf.sample /etc/esi-leap/esi-leap.conf
+tox -egenconfig
+sudo mkdir /etc/esi-leap
+sudo cp etc/esi-leap/esi-leap.conf.sample /etc/esi-leap/esi-leap.conf
 ```
 
 Edit `/etc/esi-leap/esi-leap.conf` with the proper values. (see sample config
@@ -120,58 +106,49 @@ password = <ironic password>
 dummy_node_dir=/tmp/nodes
 ```
 
-
-### Create the OpenStack Service
+## Create the OpenStack Service
 
 ```
-    $ openstack user create --domain default --password-prompt esi-leap
-    $ openstack role add --project service --user esi-leap admin
-    $ openstack service create --name esi-leap lease
-    $ openstack endpoint create esi-leap --region RegionOne public http://<YOUR_IP>:7777
+openstack user create --domain default --password-prompt esi-leap
+openstack role add --project service --user esi-leap admin
+openstack service create --name esi-leap lease
+openstack endpoint create esi-leap --region RegionOne public http://<YOUR_IP>:7777
 ```
 
+## Run the Services
 
-### Run the Services
-
-Start by instantiating the database:
+Start by creating the database schema:
 
 ```
-    $ sudo esi-leap-dbsync create_schema
+esi-leap-dbsync create_schema
 ```
 
 Once that's done, you can run the manager and API services:
 
 
 ```
-    $ sudo esi-leap-manager
-    $ sudo esi-leap-api
+esi-leap-manager
+esi-leap-api
 ```
 
-### Installation using Containerization
-
-By encapsulating the ESI Leap into a container, all the necessary dependencies, configurations and services are bundled into a single package.
+## Container Installation
 
-Please make sure to follow the instructions in the [Configuration](#configuration) section to generate the esi-leap.conf file.
-
-Make sure to follow the instructions in the [Create Openstack Service](#create-the-openstack-service) to create the OpenStack service and endpoint. 
-
-After that build the container image using the podman build command, as Containerfile is located in the current directory. The syntax is as follows:
+You can build an `esi-leap` container using the included `Containerfile`:
 
 ```
-    $ podman build -t <image-name> -f Containerfile . 
+podman build -t esi-leap .
 ```
 
-Once the container image is built, you can run it using the podman run command. The syntax is as follows:
+Once the container image has been built, you can run it using the `podman run` command. First, make sure you have created an appropriate configuration file following the instructions in the [Configuration](#configuraiton) section, and ensure you have added the appropriate service and endpoint to your OpenStack environment as described in [Create the OpenStack Service](#create-the-openstack-service). Then you can run the image like this:
 
 ```
-    $ podman run --name <container-name> -p <host-port>:<container-port> -d -v <path-to-esi-leap.conf-file>:/etc/esi-leap <image-name>
+podman run --name <container-name> -p <host-port>:<container-port> -d \
+  -v <path-to-esi-leap.conf-file>:/etc/esi-leap/esi-leap.conf esi-leap
 ```
 
+## Using Dummy Nodes
 
-### Using Dummy Nodes
-
-If you wish to use dummy nodes instead of Ironic nodes, simply specify the `dummy_node_dir`
-as specified above. Once you do so, add dummy nodes as follows:
+If you wish to use dummy nodes instead of Ironic nodes, simply specify the `dummy_node_dir` as specified above. Once you do so, add dummy nodes as follows:
 
 ```
 cat <<EOF > /tmp/nodes/1718
@@ -189,6 +166,4 @@ cat <<EOF > /tmp/nodes/1718
 EOF
 ```
 
-`1718` is the dummy node UUID; replace it with whatever you'd like. When creating an offer
-for this dummy node, simply specify `resource_type` as `dummy_node` and `resource_uuid` as
-`1718`.
+`1718` is the dummy node UUID; replace it with whatever you'd like. When creating an offer for this dummy node, simply specify `resource_type` as `dummy_node` and `resource_uuid` as `1718`.