Update documentation with new sections

README.rst

@@ -4,16 +4,13 @@ Telethon
 
   ⭐️ Thanks **everyone** who has starred the project, it means a lot!
 
-|logo| **Telethon** is an `asyncio
-<https://docs.python.org/3/library/asyncio.html>`_ **Python 3** library
-to interact with Telegram's API.
+|logo| **Telethon** is an asyncio_ **Python 3**
+MTProto_ library to interact with Telegram_'s API.
 
-**If you're upgrading from Telethon pre-1.0 to 1.0, please make sure to read**
-`this section of the documentation
-<https://telethon.readthedocs.io/en/latest/extra/basic/asyncio-magic.html>`_,
-or ``pip install telethon-sync`` which is compatible with `synchronous code
-<https://github.com/LonamiWebs/Telethon/tree/sync>`_. Don't forget to remove
-the asynchronous version (``pip uninstall telethon``) if you do install sync.
+.. important::
+
+    If you have code using Telethon before its 1.0 version, you must
+    read `Compatibility and Convenience`_ to learn how to migrate.
 
 What is this?
 -------------
@@ -27,7 +24,7 @@ heavy job for you, so you can focus on developing an application.
 Installing
 ----------
 
-.. code:: sh
+.. code-block:: sh
 
   pip3 install telethon
 
@@ -35,9 +32,9 @@ Installing
 Creating a client
 -----------------
 
-.. code:: python
+.. code-block:: python
 
-    from telethon import TelegramClient, sync
+    from telethon import TelegramClient, events, sync
 
     # These example values won't work. You must get your own api_id and
     # api_hash from https://my.telegram.org, under API Development.
@@ -51,7 +48,7 @@ Creating a client
 Doing stuff
 -----------
 
-.. code:: python
+.. code-block:: python
 
     print(client.get_me().stringify())
 
@@ -62,14 +59,23 @@ Doing stuff
     messages = client.get_messages('username')
     messages[0].download_media()
 
+    @client.on(events.NewMessage(pattern='(?i)hi|hello'))
+    async def handler(event):
+        await event.respond('Hey!')
+
 
 Next steps
 ----------
 
-Do you like how Telethon looks? Check out `Read The Docs
-<http://telethon.rtfd.io/>`_ for a more in-depth explanation,
-with examples, troubleshooting issues, and more useful information.
+Do you like how Telethon looks? Check out `Read The Docs`_ for a more
+in-depth explanation, with examples, troubleshooting issues, and more
+useful information.
 
+.. _asyncio: https://docs.python.org/3/library/asyncio.html
+.. _MTProto: https://core.telegram.org/mtproto
+.. _Telegram: https://telegram.org
+.. _Compatibility and Convenience: https://telethon.readthedocs.io/en/latest/extra/basic/compatibility-and-convenience.html
+.. _Read The Docs: https://telethon.readthedocs.io
 
 .. |logo| image:: logo.svg
     :width: 24pt