diff --git a/MANIFEST.in b/MANIFEST.in
index 6b4237e3fe10c8909c08d1a5482228c361bda6a8..23e0ddf7702ebe11b4ec086c824c23d4314b2780 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,4 @@
+include *.rst
 include *.txt
 recursive-include docs *.txt
 recursive-include pykat *.svg
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000000000000000000000000000000000000..04a390233fef2a4b632b085fce57924d951736bf
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,101 @@
+PyKat
+===========
+
+PyKat is a wrapper for using FINESSE (http://www.gwoptics.org/finesse).
+It aims to provide a Python toolset for automating more complex tasks
+as well as providing a GUI for manipulating and viewing simulation
+setups.
+
+Installation
+-------------
+
+The easiest way to install PyKat is through PyPi::
+
+    pip install pykat
+    
+If you are a Windows user you also have the option to download the installer at https://pypi.python.org/pypi/PyKat.
+
+You will also need to ensure that you have a fully working copy of FINESSE installed and setup on your machine.
+More details on this can be found at http://www.gwoptics.org/finesse.
+
+Usage
+------
+
+This does not detail how to use FINESSE itself, just PyKat. FINESSE related queries should
+be directed at the FINESSE manual or the forum http://kvasir.sr.bham.ac.uk/redmine/projects/finesse/boards.
+
+We highly recommend running PyKat with IPython, it has so far provided the best way to explore the various PyKat objects and output data.
+Also of use is IPythons interactive matplotlib mode - or pylab mode - which makes displaying and interacting with multiple plots easy.
+You can start pylab mode from a terminal using::
+
+    ipython -pylab
+
+Regardless of which interpreter you use, to begin using PyKat you first need to include the following::
+
+    from pykat import finesse
+    from pykat.detectors import *
+    from pykat.components import *
+    from pykat.commands import *
+    from pykat.structs import *
+
+This provides all the various FINESSE components and commands you will typically need.
+Running a simulation requires you to already know how to code FINESSE files, which is beyond
+the scope of this readme. FINESSE commands can be entered in many ways: Reading in a previous .kat
+file, creating pykat objects representing the various FINESSE commands or by wring blocks of code 
+as shown next::
+
+    import pylab as pl
+
+    code = """
+    l l1 1 0 0 n1
+    s s1 10 1 n1 n2
+    m m1 0.5 0.5 0 n2 n3
+    s s2 10 1 n3 n4
+    m m2 0.5 0.5 0 n4 n5
+    s s3 10 1 n5 n6
+
+    yaxis abs:deg
+    """
+
+    # this kat object represents one single simulation, it containts
+    # all the objects and their various states.
+    kat = finesse.kat()
+    # Currently the kat object is empty. We can fill it using a block
+    # string of normal FINESSE commands by parsing them.
+    kat.parseCommands(code)
+    # Once we have some simulation built up we can run it simply by calling...
+    out = kat.run()
+
+    # This out object contains the results from this run of the simulation.
+    # Parameters can then be changed and kat.run() can be called again producing
+    # another output object.
+    
+    # We can plot the output simply enough using pylab plotting.
+    pl.figure()
+    pl.plot(out.x, out["pd_cav"])
+    pl.xlabel(out.xlabel)
+    pl.ylabel("Intensity [W]")
+    pl.legend(out.ylabels)
+    pl.show()
+
+The above demonstates a way of packaging up a FINESSE simulation - simple or complex - and 
+including any post-processing and plotting in one Python script file. Or you can create
+kat files separately and produce Python scripts to run and process them, that choice is upto
+you, Pykat provides the means to be used in both ways.
+    
+Finesse Test Server
+----------------------
+
+A Flask based website that runs the Finesse test suites is included in PyKat. This can be hosted in Apache or run as a development server for quick testing on a system. This is a developer tool for testing FINESSE against a selection of known test cases.
+
+Prerequistes:
+    Flask
+    Numpy
+    
+Command to start server:
+
+.. code:: bash
+
+  python -m pykat.test.web_server --path=[path to create website] --port=[HTTP port] --git-bin=[path to git binary]
+
+The website can then be accessed in a web browser at the address: localhost:[port]
\ No newline at end of file
diff --git a/README.txt b/README.txt
deleted file mode 100644
index abd17f7ba75b5307d5c5c6791cd262287ae3913d..0000000000000000000000000000000000000000
--- a/README.txt
+++ /dev/null
@@ -1,26 +0,0 @@
-===========
-PyKat
-===========
-
-Is a wrapper for using FINESSE (http://www.gwoptics.org/finesse).
-Aims to provide a Python toolset for automating more complex tasks
-as well as providing a GUI for manipulating and viewing simulation
-setups.
-
-
-====================
-Finesse Test Server
-====================
-
-A Flask based website that runs the Finesse test suites is included in PyKat. This can
-be hosted in Apache or run as a development server for quick testing on a system.
-
-Prerequistes:
-    Flask
-    Numpy
-    
-Command to start server:
-
-python -m pykat.test.web_server --path=[path to create website] --port=[HTTP port] --git-bin=[path to git binary]
-
-The website can then be accessed by: http://localhost:[port]
diff --git a/setup.py b/setup.py
index 2722f1666d1ee0503331201db46331fe81df182c..295fd88e2bf0d2b15a32922434afb91024aba9b3 100644
--- a/setup.py
+++ b/setup.py
@@ -11,13 +11,13 @@ REQUIREMENTS = [i.strip() for i in open("requirements.txt").readlines()]
 
 setup(
     name='PyKat',
-    version='0.0.5',
+    version='0.2.4',
     author='Daniel Brown',
     author_email='ddb@star.sr.bham.ac.uk',
     packages=['pykat','pykat.gui','pykat.gui.resources','pykat.testing','pykat.testing.web'],
     url='http://pypi.python.org/pypi/PyKat/',
-    license='LICENSE.txt',
+    license='GPL v2',
     description='Python interface and tools for FINESSE',
-    long_description=open('README.txt').read(),
+    long_description=open('README.rst').read(),
     install_requires=REQUIREMENTS
 )
\ No newline at end of file