diff --git a/contrib/pylightning/README.md b/contrib/pylightning/README.md
index fe18070d1..6c3324d43 100644
--- a/contrib/pylightning/README.md
+++ b/contrib/pylightning/README.md
@@ -1,21 +1,38 @@
 # pylightning: A python client library for lightningd
 
-### Installation
+This package implements the Unix socket based JSON-RPC protocol that
+`lightningd` exposes to the rest of the world. It can be used to call
+arbitrary functions on the RPC interface, and serves as a basis for plugins
+written in python.
 
-Note: With Python 2 you need to have the futures python library installed to be able to use pylightning:
 
-```
-pip install futures
-```
+## Installation
 
-pylightning is available on pip 
+pylightning is available on `pip`:
 
 ```
 pip install pylightning
 ```
 
-### Examples
+Alternatively you can also install the development version to get access to
+currently unreleased features by checking out the c-lightning source code and
+installing into your python3 environment:
 
+```bash
+git clone https://github.com/ElementsProject/lightning.git
+cd lightning/contrib/pylightning
+python3 setup.py develop
+```
+
+This will add links to the library into your environment so changing the
+checked out source code will also result in the environment picking up these
+changes. Notice however that unreleased versions may change API without
+warning, so test thoroughly with the released version.
+
+## Examples
+
+
+### Using the JSON-RPC client
 ```py
 """
 Generate invoice on one daemon and pay it on the other
@@ -42,10 +59,43 @@ print(route)
 print(l1.sendpay(route['route'], invoice['payment_hash']))
 ```
 
-Also see the included [lightning-pay](./lightning-pay) script, which uses the client library to pay invoices
+### Writing a plugin
+
+Plugins are programs that `lightningd` can be configured to execute alongside
+the main daemon. They allow advanced interactions with and customizations to
+the daemon.
+
+```python
+#!/usr/bin/env python3
+from lightning import Plugin
+
+plugin = Plugin()
+
+@plugin.method("hello")
+def hello(plugin, name="world"):
+    """This is the documentation string for the hello-function.
+
+    It gets reported as the description when registering the function
+    as a method with `lightningd`.
+
+    """
+    greeting = plugin.get_option('greeting')
+    s = '{} {}'.format(greeting, name)
+    plugin.log(s)
+    return s
+
+
+@plugin.init()
+def init(options, configuration, plugin):
+    plugin.log("Plugin helloworld.py initialized")
+
+
+@plugin.subscribe("connect")
+def on_connect(plugin, id, address):
+    plugin.log("Received connect event for peer {}".format(id))
+
+
+plugin.add_option('greeting', 'Hello', 'The greeting I should use.')
+plugin.run()
 
-```sh
-lightning-pay <bolt11 invoice>
-# or explicitly with
-lightning-pay <destination_id> <amount in millisatoshi> <payment_hash> <min_final_cltv_expiry>
 ```
diff --git a/contrib/pylightning/setup.py b/contrib/pylightning/setup.py
index acb166bba..eeb99bac4 100644
--- a/contrib/pylightning/setup.py
+++ b/contrib/pylightning/setup.py
@@ -1,8 +1,13 @@
 from setuptools import setup
 
+with open('README.md', encoding='utf-8') as f:
+    long_description = f.read()
+
 setup(name='pylightning',
       version='0.0.6',
       description='Client library for lightningd',
+      long_description=long_description,
+      long_description_content_type='text/markdown',
       url='http://github.com/ElementsProject/lightning',
       author='Christian Decker',
       author_email='decker.christian@gmail.com',