From 7fa091719c74a5a70a193287edb32db374612363 Mon Sep 17 00:00:00 2001
From: Dan <14043624+delivrance@users.noreply.github.com>
Date: Sun, 24 Apr 2022 11:56:07 +0200
Subject: [PATCH] Add documentation page about synchronous usage

---
 docs/source/index.rst              | 14 ++++--
 docs/source/topics/synchronous.rst | 73 ++++++++++++++++++++++++++++++
 2 files changed, 82 insertions(+), 5 deletions(-)
 create mode 100644 docs/source/topics/synchronous.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 89a8ae89..c3f5d352 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -69,8 +69,11 @@ How the Documentation is Organized
 ----------------------------------
 
 Contents are organized into sections composed of self-contained topics which can be all accessed from the sidebar, or by
-following them in order using the :guilabel:`Next` button at the end of each page. Here below you can, instead, find a
-list of the most relevant pages for a quick access.
+following them in order using the :guilabel:`Next` button at the end of each page.
+You can also switch to Dark or Light theme or leave on Auto (follows system preferences) by using the dedicated button
+in the top left corner.
+
+Here below you can, instead, find a list of the most relevant pages for a quick access.
 
 First Steps
 ^^^^^^^^^^^
@@ -144,11 +147,12 @@ Meta
     topics/use-filters
     topics/create-filters
     topics/more-on-updates
-    topics/smart-plugins
     topics/client-settings
-    topics/tgcrypto
-    topics/storage-engines
+    topics/synchronous
     topics/text-formatting
+    topics/tgcrypto
+    topics/smart-plugins
+    topics/storage-engines
     topics/serializing
     topics/proxy
     topics/scheduling
diff --git a/docs/source/topics/synchronous.rst b/docs/source/topics/synchronous.rst
new file mode 100644
index 00000000..e082f18c
--- /dev/null
+++ b/docs/source/topics/synchronous.rst
@@ -0,0 +1,73 @@
+Synchronous Usage
+=================
+
+Pyrogram is an asynchronous framework and as such it is subject to the asynchronous rules. It can, however, run in
+synchronous mode (also known as non-asynchronous or sync/non-async for short). This mode exists mainly as a convenience
+way for invoking methods without the need of ``async``/``await`` keywords and the extra boilerplate, but **it's not the
+intended way to use the framework**.
+
+You can use Pyrogram in this synchronous mode when you want to write something short and contained without the
+async boilerplate or in case you want to combine Pyrogram with other libraries that are not async.
+
+.. warning::
+
+    You have to be very careful when using the framework in its synchronous, non-native form, especially when combined
+    with other non-async libraries because thread blocking operations that clog the asynchronous event loop underneath
+    will make the program run erratically.
+
+.. contents:: Contents
+    :backlinks: none
+    :depth: 1
+    :local:
+
+-----
+
+Synchronous Invocations
+-----------------------
+
+The following is a standard example of running asynchronous functions with Python's asyncio.
+Pyrogram is being used inside the main function with its asynchronous interface.
+
+.. code-block:: python
+
+    import asyncio
+    from pyrogram import Client
+
+
+    async def main():
+        app = Client("my_account")
+
+        async with app:
+            await app.send_message("me", "Hi!")
+
+
+    asyncio.run(main())
+
+To run Pyrogram synchronously, use the non-async context manager as shown in the following example.
+As you can see, the non-async example becomes less cluttered.
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+
+    with app:
+        app.send_message("me", "Hi!")
+
+Synchronous handlers
+--------------------
+
+You can also have synchronous handlers; you only need to define the callback function without using ``async def`` and
+invoke API methods by not placing ``await`` in front of them. Mixing ``def`` and ``async def`` handlers together is also
+possible.
+
+.. code-block:: python
+
+    @app.on_message()
+    async def handler1(client, message):
+        await message.forward("me")
+
+    @app.on_edited_message()
+    def handler2(client, message):
+        message.forward("me")