Fix up README formatting

2 files changed, 96 insertions, 78 deletions

diff --git a/README.md b/README.md
deleted file mode 100644
index 13177cc..0000000
--- a/README.md
+++ /dev/null
@@ -1,78 +0,0 @@
-python-mpv
-==========
-
-python-mpv is a ctypes-based python interface to the mpv media player. It gives you more or less full control of all
-features of the player, just as the lua interface does.
-
-Installation
-============
-```bash
-wget -O mpv.py https://raw.githubusercontent.com/jaseg/python-mpv/master/mpv.py
-```
-
-Seriously though, part of the idea of this being all in one handy file is that you can just copy it into your project.
-That also means you don't need to be afraid of customizing it, as it's really not a lot of code. 
-
-Usage
-=====
-```python
-import mpv
-player = mpv.MPV(ytdl=True)
-player.play('https://youtu.be/DOmdB7D-pUU')
-```
-
-Threading
----------
-The ```mpv``` module starts one thread for event handling, since MPV sends events that must be processed quickly. The event queue has a fixed maxmimum size and some operations can cause a large number of events to be sent.
-
-If you want to handle threading yourself, you can pass ```start_event_thread=False``` to the ```MPV``` constructor and manually call the ```MPV``` object's ```_loop``` function. If you have some strong need to not use threads and use some external event loop (such as asyncio) instead you can do that, too with some work. The API of the backend C ```libmpv``` has a function for producing a sort of event file descriptor for a handle. You can use that to produce a file descriptor that can be passed to an event loop to tell it to wake up the python-mpv event handler on every incoming event.
-
-All API functions are thread-safe. If one is not, please file an issue on github.
-
-Advanced Usage
-==============
-```python
-#!/usr/bin/env python3
-import mpv
-
-def my_log(loglevel, component, message):
-	print('[{}] {}: {}'.format(loglevel, component, message))
-
-player = mpv.MPV(log_handler=my_log, ytdl=True, input_default_bindings=True, input_vo_keyboard=True)
-
-# Property access, these can be changed at runtime
-player.observe_property('time-pos', lambda pos: print('Now playing at {:.2f}s'.format(pos)))
-player.fullscreen = True
-player.loop = 'inf'
-# Option access, in general these require the core to reinitialize
-player['vo'] = 'opengl'
-
-def my_q_binding(state, key):
-    if state[0] == 'd':
-        print('THERE IS NO ESCAPE')
-player.register_key_binding('q', my_q_binding)
-
-player.play('https://youtu.be/DLzxrzFCyOs')
-player.wait_for_playback()
-
-del player
-
-```
-
-```python
-#!/usr/bin/env python3
-import mpv
-
-player = mpv.MPV(ytdl=True, input_default_bindings=True, input_vo_keyboard=True)
-
-player.playlist_append('https://youtu.be/PHIGke6Yzh8')
-player.playlist_append('https://youtu.be/Ji9qSuQapFY')
-player.playlist_append('https://youtu.be/6f78_Tf4Tdk')
-
-player.playlist_pos = 0
-
-while True:
-    # To modify the playlist, use player.playlist_{append,clear,move,remove}. player.playlist is read-only
-	print(player.playlist)
-	player.wait_for_playback()
-```
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..7016bd7
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,96 @@
+python-mpv
+==========
+
+python-mpv is a ctypes-based python interface to the mpv media player. It gives you more or less full control of all
+features of the player, just as the lua interface does.
+
+Installation
+------------
+
+.. code:: bash
+
+    wget -O mpv.py https://raw.githubusercontent.com/jaseg/python-mpv/master/mpv.py
+
+Seriously though, part of the idea of this being all in one handy file is that you can just copy it into your project.
+That also means you don't need to be afraid of customizing it, as it's really not a lot of code. 
+
+Usage
+-----
+
+.. code:: python
+
+    import mpv
+    player = mpv.MPV(ytdl=True)
+    player.play('https://youtu.be/DOmdB7D-pUU')
+
+
+Threading
+~~~~~~~~~
+
+The ``mpv`` module starts one thread for event handling, since MPV sends events that must be processed quickly. The
+event queue has a fixed maxmimum size and some operations can cause a large number of events to be sent.
+
+If you want to handle threading yourself, you can pass ``start_event_thread=False`` to the ``MPV`` constructor and
+manually call the ``MPV`` object's ``_loop`` function. If you have some strong need to not use threads and use some
+external event loop (such as asyncio) instead you can do that, too with some work. The API of the backend C ``libmpv``
+has a function for producing a sort of event file descriptor for a handle. You can use that to produce a file descriptor
+that can be passed to an event loop to tell it to wake up the python-mpv event handler on every incoming event.
+
+All API functions are thread-safe. If one is not, please file an issue on github.
+
+Advanced Usage
+~~~~~~~~~~~~~~
+
+.. code:: python
+
+    #!/usr/bin/env python3
+    import mpv
+
+    def my_log(loglevel, component, message):
+        print('[{}] {}: {}'.format(loglevel, component, message))
+
+    player = mpv.MPV(log_handler=my_log, ytdl=True, input_default_bindings=True, input_vo_keyboard=True)
+
+    # Property access, these can be changed at runtime
+    player.observe_property('time-pos', lambda pos: print('Now playing at {:.2f}s'.format(pos)))
+    player.fullscreen = True
+    player.loop = 'inf'
+    # Option access, in general these require the core to reinitialize
+    player['vo'] = 'opengl'
+
+    def my_q_binding(state, key):
+        if state[0] == 'd':
+            print('THERE IS NO ESCAPE')
+    player.register_key_binding('q', my_q_binding)
+
+    player.play('https://youtu.be/DLzxrzFCyOs')
+    player.wait_for_playback()
+
+    del player
+
+.. code:: python
+
+    #!/usr/bin/env python3
+    import mpv
+
+    player = mpv.MPV(ytdl=True, input_default_bindings=True, input_vo_keyboard=True)
+
+    player.playlist_append('https://youtu.be/PHIGke6Yzh8')
+    player.playlist_append('https://youtu.be/Ji9qSuQapFY')
+    player.playlist_append('https://youtu.be/6f78_Tf4Tdk')
+
+    player.playlist_pos = 0
+
+    while True:
+        # To modify the playlist, use player.playlist_{append,clear,move,remove}. player.playlist is read-only
+        print(player.playlist)
+        player.wait_for_playback()
+
+Coding conventions
+------------------
+
+The general aim is `PEP 8`_, with liberal application of the "consistency" section. 120 cells line width. Four spaces.
+No tabs. Probably don't bother making pure-formatting PRs except if you think it *really* helps readability or it
+*really* irks you if you don't.
+
+.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/