Revamp docs and move wiki content here

docs/source/errors/BadRequest.rst

@@ -1,6 +1,8 @@
 Bad Request
 ===========
 
+.. module:: pyrogram.api.errors.BadRequest
+
 .. automodule:: pyrogram.api.errors.exceptions.bad_request_400
     :members:
     :show-inheritance:

docs/source/errors/Flood.rst

@@ -1,6 +1,8 @@
 Flood
 =====
 
+.. module:: pyrogram.api.errors.Flood
+
 .. automodule:: pyrogram.api.errors.exceptions.flood_420
     :members:
     :show-inheritance:

docs/source/errors/InternalServerError.rst

@@ -1,6 +1,8 @@
 Internal Server Error
 =====================
 
+.. module:: pyrogram.api.errors.InternalServerError
+
 .. automodule:: pyrogram.api.errors.exceptions.internal_server_error_500
     :members:
     :show-inheritance:

docs/source/errors/SeeOther.rst

@@ -1,6 +1,8 @@
 See Other
 =========
 
+.. module:: pyrogram.api.errors.SeeOther
+
 .. automodule:: pyrogram.api.errors.exceptions.see_other_303
     :members:
     :show-inheritance:

docs/source/errors/Unauthorized.rst

@@ -1,6 +1,8 @@
 Unauthorized
 ============
 
+.. module:: pyrogram.api.errors.Unauthorized
+
 .. automodule:: pyrogram.api.errors.exceptions.unauthorized_401
     :members:
     :show-inheritance:

docs/source/errors/UnknownError.rst

@@ -1,6 +1,8 @@
 Unknown Error
 =============
 
+.. module:: pyrogram.api.errors.UnknownError
+
 .. autoclass:: pyrogram.api.errors.error.UnknownError
     :members:
     :show-inheritance:

docs/source/getting_started/BasicUsage.rst

@@ -0,0 +1,71 @@
+Basic Usage
+===========
+
+.. note::
+
+    All the snippets below assume you have successfully created and started a :obj:`pyrogram.Client` instance.
+    You also must be authorized, that is, a valid *.session file does exist in your working directory.
+
+Simple API Access
+-----------------
+
+The easiest way to interact with the API is via the :obj:`pyrogram.Client` class which exposes bot-like_ methods.
+The purpose of this Client class is to make it even simpler to work with Telegram's API by abstracting the
+raw functions listed in the API scheme.
+
+The result is a much cleaner interface that allows you to:
+
+-   Get information about the authorized user:
+
+    .. code-block:: python
+
+        print(client.get_me())
+
+-   Send a message to yourself (Saved Messages):
+
+    .. code-block:: python
+
+        client.send_message(
+            chat_id="me",
+            text="Hi there! I'm using Pyrogram"
+        )
+
+.. seealso:: For a complete list of the available methods have a look at the :obj:`pyrogram.Client` class.
+
+Using Raw Functions
+-------------------
+
+If you want **complete**, low-level access to the Telegram API you have to use the raw
+:obj:`functions <pyrogram.api.functions>` and :obj:`types <pyrogram.api.types>` exposed by the ``pyrogram.api``
+package and call any Telegram API method you wish using the :obj:`send <pyrogram.Client.send>` method provided by
+the Client class.
+
+Here some examples:
+
+-   Update first name, last name and bio:
+
+    .. code-block:: python
+
+        from pyrogram.api import functions
+
+        client.send(
+            functions.account.UpdateProfile(
+                first_name="Dan", last_name="Tès",
+                about="Bio written from Pyrogram"
+            )
+        )
+
+-   Share your Last Seen time only with your contacts:
+
+    .. code-block:: python
+
+        from pyrogram.api import functions, types
+
+        client.send(
+            functions.account.SetPrivacy(
+                key=types.InputPrivacyKeyStatusTimestamp(),
+                rules=[types.InputPrivacyValueAllowContacts()]
+            )
+        )
+
+.. _bot-like: https://core.telegram.org/bots/api#available-methods

docs/source/getting_started/ProjectSetup.rst

@@ -0,0 +1,66 @@
+Project Setup
+=============
+
+This section provides all the information you need to setup your project with Pyrogram.
+There are a few steps you have to follow before you can actually use the library to make API calls.
+
+API Keys
+--------
+
+The very first step requires you to obtain a valid Telegram API key.
+If you already have one you can skip this, otherwise:
+
+#. Visit https://my.telegram.org/apps and log in with your Telegram Account.
+#. Fill out the form to register a new Telegram application.
+#. Done. The Telegram API key consists of two parts: the **App api_id** and the **App api_hash**
+
+.. important:: This key should be kept secret.
+
+Configuration
+-------------
+
+Create a new ``config.ini`` file at the root of your working directory,
+copy-paste the following and replace the **api_id** and **api_hash** values with `your own <#api-keys>`_:
+
+.. code-block:: ini
+
+    [pyrogram]
+    api_id = 12345
+    api_hash = 0123456789abcdef0123456789abcdef
+
+Authorization
+-------------
+
+Telegram requires that users be authorized in order to use the API.
+Pyrogram automatically manages this access, all you need to do is create an instance of
+the :class:`pyrogram.Client` class by passing to it a ``<session_name>`` of your choice
+and call the :obj:`start <pyrogram.Client.start>` method:
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    client = Client(session_name="example")
+    client.start()
+
+This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_)
+and the **phone code** you will receive:
+
+.. code::
+
+    Enter phone number: +39**********
+    Is "+39**********" correct? (y/n): y
+    Enter phone code: 32768
+
+After successfully authorizing yourself, a new file called ``example.session`` will be created allowing
+Pyrogram executing API calls with your identity.
+
+.. important:: Your *.session file(s) must be kept secret.
+
+.. note::
+
+    The authorization process is executed only once.
+    However, the code above is always required; as soon as a valid session file exists,
+    Pyrogram will use that and won't ask you to enter your phone number again when you restart your script.
+
+.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes

docs/source/getting_started/QuickInstallation.rst

@@ -0,0 +1,37 @@
+Quick Installation
+==================
+
+The most straightforward and recommended way to install or upgrade Pyrogram is by using **pip**:
+
+.. code-block:: bash
+
+    $ pip install --upgrade pyrogram
+
+Bleeding Edge
+-------------
+
+If you want the latest development version of the library, you can either install it automatically with:
+
+.. code-block:: bash
+
+    $ pip install git+https://github.com/pyrogram/pyrogram.git
+
+or manually, using:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/pyrogram/pyrogram.git
+    $ cd pyrogram
+    $ python setup.py install
+
+Verifying
+---------
+
+To verify that Pyrogram is correctly installed, open a Python shell and try to import it.
+If no errors show up you are good to go.
+
+.. code-block:: bash
+
+    >>> import pyrogram
+    >>> pyrogram.__version__
+    '0.3.2'

docs/source/index.rst

@@ -13,26 +13,54 @@ Welcome to Pyrogram
         <b>Telegram MTProto API Client Library for Python</b>
     </p>
 
-Welcome to Pyrogram's documentation. Here you can find a detailed description of the Pyrogram API.
+Preview
-You will notice that methods are named after the well established `Telegram Bot API`_ and that most of them
+-------
-accept the same parameters as well.
 
-.. note::
+.. code-block:: python
-    This document is intended to be used as an API reference documentation.
+
-    For more information on how to install and setup the library, please refer to the Wiki_.
+    from pyrogram import Client
+
+    client = Client("example")
+    client.start()
+
+    client.send_message("me", "Hi there! I'm using Pyrogram")
+    client.send_photo("me", "/home/dan/pic.jpg", "Nice photo!")
+
+    client.stop()
+
+About
+-----
+
+Welcome to the Pyrogram's documentation! Here you can find resources for learning how to use the library.
+Contents are organized by topic and are accessible from the sidebar.
+
+To get started, press Next.
 
 .. toctree::
+    :hidden:
+    :caption: Getting Started
+
+    getting_started/QuickInstallation
+    getting_started/ProjectSetup
+    getting_started/BasicUsage
+
+.. toctree::
+    :hidden:
+    :caption: Resources
+
+    resources/TextFormatting
+    resources/UpdateHandling
+    resources/ErrorHandling
+
+.. toctree::
+    :hidden:
     :caption: Main Package
 
     pyrogram/index
 
 .. toctree::
-    :caption: Telegram API - Layer 74
+    :hidden:
+    :caption: Telegram API
 
     functions/index
     types/index
-
-
-.. _Wiki: https://github.com/pyrogram/pyrogram/wiki
-
-.. _`Telegram Bot API`: https://core.telegram.org/bots/api#available-methods

docs/source/pyrogram/index.rst

@@ -1,7 +1,15 @@
 Pyrogram
 ========
 
+In this section you can find a detailed description of the Pyrogram API.
+
+:obj:`pyrogram.Client` is the main class you have to deal with.
+You will notice that methods are named after the well established `Telegram Bot API`_ and that most of them accept
+the same parameters as well, thus offering a familiar look to Bot developers.
+
 .. toctree::
     Client
     ChatAction
     Error
+
+.. _Telegram Bot API: https://core.telegram.org/bots/api#available-methods

docs/source/resources/ErrorHandling.rst

@@ -0,0 +1,61 @@
+Error Handling
+==============
+
+Errors are inevitable when working with the API, and they must be correctly handled by
+the use of ``try..except`` blocks.
+
+There are many errors that Telegram could return, but they all fall in one of these five exception categories
+(which are in turn children of the :obj:`pyrogram.Error` superclass)
+
+-   :obj:`303 See Other <pyrogram.api.errors.SeeOther>`
+-   :obj:`400 Bad Request <pyrogram.api.errors.BadRequest>`
+-   :obj:`401 Unauthorized <pyrogram.api.errors.Unauthorized>`
+-   :obj:`420 Flood <pyrogram.api.errors.Flood>`
+-   :obj:`500 Internal Server Error <pyrogram.api.errors.InternalServerError>`
+
+As stated above, there are really many (too many) errors, and in case Pyrogram does not know anything yet about a
+specific one, it raises a special :obj:`520 Unknown Error <pyrogram.api.errors.UnknownError>` exception and logs it
+in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors; in later versions of Pyrogram
+some kind of automatic error reporting module might be implemented.
+
+Examples
+--------
+
+.. code-block:: python
+
+    from pyrogram.api.errors import (
+        BadRequest, Flood, InternalServerError,
+        SeeOther, Unauthorized, UnknownError
+    )
+
+    try:
+        # Something
+        pass
+    except BadRequest:
+        pass
+    except Flood:
+        pass
+    except InternalServerError:
+        pass
+    except SeeOther:
+        pass
+    except Unauthorized:
+        pass
+    except UnknownError:
+        pass
+
+Exceptions may also contain some informative values which can be useful.
+e.g. :obj:`FloodWait <pyrogram.api.errors.exceptions.flood_420.FloodWait>` holds the amount of seconds you have to wait before you
+can try again. The value is always stored in the ``x`` field of the returned exception object:
+
+.. code-block:: python
+
+    from pyrogram.api.errors import FloodWait
+
+    try:
+        # something
+        pass
+    except FloodWait as e:
+        print(e.x)
+
+**TODO: Better explanation on how to deal with exceptions**

docs/source/resources/TextFormatting.rst

@@ -0,0 +1,55 @@
+Text Formatting
+===============
+
+Pyrogram, just like `Telegram Bot API`_, supports basic Markdown formatting for messages;
+it uses the same syntax as Telegram Desktop's and is enabled by default.
+Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline URLs and inline mentions of users**.
+
+Here is the complete syntax you can use when sending or editing messages:
+
+.. code::
+
+    **bold text**
+
+    __italic text__
+
+    [inline URL](http://www.example.com/)
+
+    [inline mention of a user](tg://user?id=123456789)
+
+    `inline fixed-width code`
+
+    ```block_language
+    pre-formatted fixed-width code block
+    ```
+
+Code Snippets
+-------------
+
+-   Inline entities (bold, italic, ...):
+
+    .. code-block:: python
+
+        client.send_message(
+            chat_id="me",
+            text="**bold**, __italic__, [mention](tg://user?id=23122162), [url](https://pyrogram.ml), `code`"
+        )
+
+    .. note:: Mentions are only guaranteed to work if you have already contacted the user.
+
+-   Code blocks:
+
+    .. code-block:: python
+
+        client.send_message(
+            chat_id="me",
+            text=(
+                # Code block language is optional
+                "``` python\n"
+                "for i in range(10):\n"
+                "   print(i)\n"
+                "```"
+            )
+        )
+
+.. _Telegram Bot API: https://core.telegram.org/bots/api#formatting-options

docs/source/resources/UpdateHandling.rst

@@ -0,0 +1,46 @@
+Update Handling
+===============
+
+Updates are events that happen in your Telegram account (incoming messages, new channel posts, user name changes, ...)
+and can be handled by using a callback function, that is, a function called every time an ``Update`` is received from
+Telegram.
+
+To set an update handler simply call :obj:`set_update_handler <pyrogram.Client.set_update_handler>`
+by passing the name of your defined callback function as argument *before* you start the Client.
+
+Here's a complete example on how to set it up:
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+
+    def callback(update):
+        print(update)
+
+
+    client = Client(session_name="example")
+    client.set_update_handler(callback)
+
+    client.start()
+    client.idle()
+
+The last line, :obj:`client.idle() <pyrogram.Client.idle>` is not strictly necessary but highly recommended;
+it will block your script execution until you press :obj:`CTRL`:obj:`C` and automatically call the
+:obj:`stop <pyrogram.Client.stop>` method which stops the Client and gently close the underlying connection.
+
+Examples
+--------
+
+-   Echo:
+
+    .. code-block:: python
+
+        from pyrogram.api import types
+
+        def callback(update):
+            if isinstance(update, types.UpdateShortMessage) and not update.out:
+                client.send_message(update.user_id, update.message)
+
+    This checks if the update type is :obj:`types.UpdateShortMessage <pyrogram.api.types.UpdateShortMessage>` and that the
+    update is not generated by yourself (i.e., the message is not outgoing), then sends back the same message.