Update docs

docs/source/start/errors.rst

@@ -1,7 +1,7 @@
 Error Handling
 ==============
 
-Errors are inevitable when working with the API, and they must be correctly handled with ``try..except`` blocks in order
+Errors are inevitable when working with the API, and they can be correctly handled with ``try...except`` blocks in order
 to control the behaviour of your application. Pyrogram errors all live inside the ``errors`` package:
 
 .. code-block:: python

docs/source/start/examples/bot_keyboards.rst

@@ -11,7 +11,8 @@ like send_audio(), send_document(), send_location(), etc...
 
 .. code-block:: python
 
-    from pyrogram import Client, ReplyKeyboardMarkup, InlineKeyboardMarkup, InlineKeyboardButton
+    from pyrogram import Client
+    from pyrogram.types import ReplyKeyboardMarkup, InlineKeyboardMarkup, InlineKeyboardButton
 
     # Create a client using your bot token
     app = Client("my_bot", bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11")

docs/source/start/examples/echobot.rst

@@ -3,19 +3,19 @@ echobot
 
 This simple echo bot replies to every private text message.
 
-It uses the @on_message decorator to register a MessageHandler and applies two filters on it:
-Filters.text and Filters.private to make sure it will reply to private text messages only.
+It uses the ``@on_message`` decorator to register a ``MessageHandler`` and applies two filters on it:
+``filters.text`` and ``filters.private`` to make sure it will reply to private text messages only.
 
 .. code-block:: python
 
-    from pyrogram import Client, Filters
+    from pyrogram import Client, filters
 
     app = Client("my_account")
 
 
-    @app.on_message(Filters.text & Filters.private)
+    @app.on_message(filters.text & filters.private)
     def echo(client, message):
-        message.reply(message.text)
+        message.reply_text(message.text)
 
 
     app.run()  # Automatically start() and idle()

docs/source/start/examples/inline_queries.rst

@@ -8,9 +8,9 @@ It uses the @on_inline_query decorator to register an InlineQueryHandler.
 
 .. code-block:: python
 
-    from pyrogram import (
-        Client, InlineQueryResultArticle, InputTextMessageContent, InlineKeyboardMarkup, InlineKeyboardButton
-    )
+    from pyrogram import Client
+    from pyrogram.types import (InlineQueryResultArticle, InputTextMessageContent,
+                                InlineKeyboardMarkup, InlineKeyboardButton)
 
     app = Client("my_bot", bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11")
 

docs/source/start/examples/welcomebot.rst

@@ -1,14 +1,12 @@
 welcomebot
 ==========
 
-This is the Welcome Bot in @PyrogramChat.
-
-It uses the Emoji module to easily add emojis in your text messages and Filters
+This example uses the ``emoji`` module to easily add emoji in your text messages and ``filters``
 to make it only work for specific messages in a specific chat.
 
 .. code-block:: python
 
-    from pyrogram import Client, Emoji, Filters
+    from pyrogram import Client, emoji, filters
 
     TARGET = "PyrogramChat"  # Target chat. Can also be a list of multiple chat ids/usernames
     MENTION = "[{}](tg://user?id={})"  # User mention markup
@@ -18,16 +16,16 @@ to make it only work for specific messages in a specific chat.
 
 
     # Filter in only new_chat_members updates generated in TARGET chat
-    @app.on_message(Filters.chat(TARGET) & Filters.new_chat_members)
+    @app.on_message(filters.chat(TARGET) & filters.new_chat_members)
     def welcome(client, message):
         # Build the new members list (with mentions) by using their first_name
-        new_members = [MENTION.format(i.first_name, i.id) for i in message.new_chat_members]
+        new_members = [u.mention for u in message.new_chat_members]
 
         # Build the welcome message by using an emoji and the list we built above
-        text = MESSAGE.format(Emoji.SPARKLES, ", ".join(new_members))
+        text = MESSAGE.format(emoji.SPARKLES, ", ".join(new_members))
 
         # Send the welcome message, without the web page preview
-        message.reply(text, disable_web_page_preview=True)
+        message.reply_text(text, disable_web_page_preview=True)
 
 
     app.run()  # Automatically start() and idle()

docs/source/start/invoking.rst

@@ -14,8 +14,7 @@ account; we are now aiming towards the core of the library. It's time to start p
 Basic Usage
 -----------
 
-Making API method calls with Pyrogram is very simple. Here's a basic example we are going to examine step by step and
-then expand to explain what happens underneath:
+Making API method calls with Pyrogram is very simple. Here's a basic example we are going to examine step by step:
 
 .. code-block:: python
 
@@ -56,9 +55,9 @@ Basic step-by-step
 Context Manager
 ---------------
 
-The ``with`` statement starts a context manager, which is used as a shortcut to automatically call
-:meth:`~pyrogram.Client.start` and :meth:`~pyrogram.Client.stop`, which are methods required for Pyrogram to work
-properly. The context manager does also gracefully stop the client, even in case of unhandled exceptions in your code.
+The ``with`` statement starts a context manager used as a shortcut to automatically call :meth:`~pyrogram.Client.start`
+and :meth:`~pyrogram.Client.stop`, which are methods required for Pyrogram to work properly. The context manager does
+also gracefully stop the client, even in case of unhandled exceptions in your code.
 
 This is how Pyrogram looks without the context manager:
 
@@ -111,8 +110,8 @@ Asynchronous step-by-step
             async with app:
                 await app.send_message("me", "Hi!")
 
-#.  Finally, we tell Python to schedule our ``main()`` async function, which in turn will execute Pyrogram's code. Using
-    :meth:`~pyrogram.Client.run` this way is a friendly alternative for the much more verbose
+#.  Finally, we tell Python to schedule our ``main()`` async function, which in turn will execute Pyrogram's methods.
+    Using :meth:`~pyrogram.Client.run` this way is a friendly alternative for the much more verbose
     ``asyncio.get_event_loop().run_until_complete(main())``:
 
     .. code-block:: python

docs/source/start/updates.rst

@@ -26,8 +26,8 @@ Registering a Handler
 ---------------------
 
 To explain how handlers work let's examine the one which will be in charge for handling :class:`~pyrogram.types.Message`
-updates coming from all around your chats. Every other handler shares the same setup logic; you should not have
-troubles settings them up once you learn from this section.
+updates coming from all around your chats. Every other kind of handler shares the same setup logic and you should not
+have troubles settings them up once you learn from this section.
 
 Using Decorators
 ^^^^^^^^^^^^^^^^
@@ -98,3 +98,9 @@ The same about asynchronous handlers applies for :meth:`~pyrogram.Client.add_han
 
     async def my_function(client, message):
         await message.forward("me")
+
+.. note::
+
+    From now on, you'll see examples using synchronous code (i.e.: without ``async`` and ``await``, unless when actually
+    relevant). This is done to keep snippets concise and more readable. Once you get the idea behind a feature, you can
+    easily turn examples asynchronous later on.