From 1e77ab605106aa0cc9c22b36a9b6970da11125a4 Mon Sep 17 00:00:00 2001
From: Chris Timperley <christimperley@googlemail.com>
Date: Mon, 24 Jun 2019 16:15:51 -0400
Subject: [PATCH] Improved README (#275)

* updated readme:

* indentation fix

* grammar fix
---
 README.rst | 61 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 47 insertions(+), 14 deletions(-)

diff --git a/README.rst b/README.rst
index 3432c2ef..fcac188b 100644
--- a/README.rst
+++ b/README.rst
@@ -6,22 +6,55 @@ roswire
 .. image:: https://travis-ci.org/ChrisTimperley/roswire.svg?branch=master
     :target: https://travis-ci.org/ChrisTimperley/roswire
 
-Feature Roadmap
-----------------
 
-* Supports ROS 1 and 2.
-* Differential coverage collection for C, C++ and Java.
-* Highly parallel: interact with multiple systems simultaneously.
-* Mutation API: quickly apply random source-code mutations to SUTs.
-* Simulation speedup.
-* Plugin-based simulator support.
-* Modular oracles.
-* Trace collection and streaming.
+ROSWire is a Python library for static and dynamic analysis of
+containerised `Robot Operating System (ROS) <https://ros.org>`_
+applications.
+Given a `Docker <https://docker.org>`_ image,
+ROSWire provides an interface for statically querying the application
+(e.g., by automatically discovering its types, packages, messages, service,
+actions, etc.), as well as an interface for dynamically generating and
+interacting with instances of that application in the form of Docker
+containers (e.g., service calls, bag recording, topic publishing and
+subscribing, catkin builds, etc.).
 
 
-Applications
+Features
+--------
+
+* **Package Discovery:** finds all ROS packages within a Docker image.
+* **Definition Discovery:** finds and parses all message, service and
+  action formats into readable data structures.
+* **Message Serialisation:** converts ROS messages from YAML or binary
+  to readable data structures and vice versa.
+* **Bag Manipulation:** efficiently parses
+  `rosbag <http://wiki.ros.org/rosbag>`_ files, which can then be inspected,
+  manipulated, and saved to disk.
+* **Bag Playback:** safely replay bag files inside containers.
+
+
+Installation
 ------------
 
-* Property-based testing
-* Blackbox fuzzing
-* Model discovery
+To avoid interfering with the rest of your system (i.e., to avoid Python's
+equivalent of DLL hell), we strongly recommend that
+ROSWire is installed within a
+`virtualenv <https://virtualenv.pypa.io/en/latest/>`_ or
+`pipenv <https://pipenv.readthedocs.io/en/latest/>`_ (pipenv is preferred).
+
+From within the virtual environment (i.e., the `virtualenv` or `pipenv`),
+the latest stable release of ROSWire on `PyPI <https://pypi.org>`_
+can be installed via:
+
+.. code:: shell
+
+   (roswire) $ pip install roswire
+
+ROSWire can also be installed from source:
+
+.. code:: shell
+
+   $ git clone git@github.com:ChrisTimperley/roswire roswire
+   $ cd roswire
+   $ pipenv shell
+   (roswire) $ pip install .