Docs revamp. Part 2

docs/source/intro/auth.rst

@@ -0,0 +1,68 @@
+Authorization
+=============
+
+Once a `project is set up`_, you will still have to follow a few steps before you can actually use Pyrogram to make
+API calls. This section provides all the information you need in order to authorize yourself as user or a bot.
+
+User Authorization
+------------------
+
+In order to use the API, Telegram requires that users be authorized via their phone numbers.
+Pyrogram automatically manages this access, all you need to do is create an instance of the
+:class:`Client <pyrogram.Client>` class by passing to it a ``session_name`` of your choice (e.g.: "my_account") and call
+the :meth:`run() <pyrogram.Client.run>` method:
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client("my_account")
+    app.run()
+
+This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_) and the
+**phone code** you will receive in your devices that are already authorized or via SMS:
+
+.. code-block:: text
+
+    Enter phone number: +39**********
+    Is "+39**********" correct? (y/n): y
+    Enter phone code: 32768
+    Logged in successfully as Dan
+
+After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing Pyrogram to
+execute API calls with your identity. This file will be loaded again when you restart your app, and as long as you
+keep the session alive, Pyrogram won't ask you again to enter your phone number.
+
+.. important::
+
+    Your ``*.session`` files are personal and must be kept secret.
+
+.. note::
+
+    The code above does nothing except asking for credentials and keeping the client online, hit ``CTRL+C`` now to stop
+    your application and keep reading.
+
+Bot Authorization
+-----------------
+
+Bots are a special kind of users that are authorized via their tokens (instead of phone numbers), which are created by
+the `Bot Father`_. Bot tokens replace the users' phone numbers only — you still need to
+`configure a Telegram API key <setup.html#configuration>`_ with Pyrogram, even when using bots.
+
+The authorization process is automatically managed. All you need to do is choose a ``session_name`` (can be anything,
+usually your bot username) and pass your bot token using the ``bot_token`` parameter. The session file will be named
+after the session name, which will be ``pyrogrambot.session`` for the example below.
+
+.. code-block:: python
+
+    from pyrogram import Client
+
+    app = Client(
+        "my_bot",
+        bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
+    )
+    app.run()
+
+.. _project is set up: setup.html
+.. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes
+.. _Bot Father: https://t.me/botfather

docs/source/intro/install.rst

@@ -0,0 +1,92 @@
+Install Guide
+=============
+
+Being a Python library, **Pyrogram** requires Python to be installed in your system.
+We recommend using the latest versions of both Python 3 and pip.
+
+- Get **Python 3** from https://www.python.org/downloads/ (or with your package manager)
+- Get **pip** by following the instructions at https://pip.pypa.io/en/latest/installing/.
+
+.. important::
+
+    Pyrogram supports **Python 3** only, starting from version 3.4. **PyPy** is supported too.
+
+Install Pyrogram
+----------------
+
+-   The easiest way to install and upgrade Pyrogram to its latest stable version is by using **pip**:
+
+    .. code-block:: text
+
+        $ pip3 install -U pyrogram
+
+-   or, with TgCrypto_ as extra requirement (recommended):
+
+    .. code-block:: text
+
+        $ pip3 install -U pyrogram[fast]
+
+Bleeding Edge
+-------------
+
+Things are constantly evolving in Pyrogram, although new releases are published only when enough changes are added,
+but this doesn't mean you can't try new features right now!
+
+In case you would like to try out the latest Pyrogram features and additions, the `GitHub repo`_ is always kept updated
+with new changes; you can install the development version straight from the ``develop`` branch using this command
+(note "develop.zip" in the link):
+
+.. code-block:: text
+
+    $ pip3 install -U https://github.com/pyrogram/pyrogram/archive/develop.zip
+
+Asynchronous
+------------
+
+Pyrogram heavily depends on IO-bound network code (it's a cloud-based messaging framework after all), and here's
+where asyncio shines the most by providing extra performance while running on a single OS-level thread only.
+
+**A fully asynchronous variant of Pyrogram is therefore available** (Python 3.5.3+ required).
+Use this command to install (note "asyncio.zip" in the link):
+
+.. code-block:: text
+
+    $ pip3 install -U https://github.com/pyrogram/pyrogram/archive/asyncio.zip
+
+
+Pyrogram API remains the same and features are kept up to date from the non-async, default develop branch, but you
+are obviously required Python asyncio knowledge in order to take full advantage of it.
+
+
+.. tip::
+
+    The idea to turn Pyrogram fully asynchronous is still under consideration, but is wise to expect that in future this
+    would be the one and only way to work with Pyrogram.
+
+    You can start using Pyrogram Async variant right now as an excuse to learn more about asynchronous programming and
+    do experiments with it!
+
+.. raw:: html
+
+    <script async
+        src="https://telegram.org/js/telegram-widget.js?4"
+        data-telegram-post="Pyrogram/4"
+        data-width="100%">
+    </script>
+
+.. centered:: Subscribe to `@Pyrogram <https://t.me/Pyrogram>`_ for news and announcements
+
+Verifying
+---------
+
+To verify that Pyrogram is correctly installed, open a Python shell and import it.
+If no error shows up you are good to go.
+
+.. code-block:: python
+
+    >>> import pyrogram
+    >>> pyrogram.__version__
+    '0.12.0'
+
+.. _TgCrypto: ../resources/tgcrypto.html
+.. _`Github repo`: http://github.com/pyrogram/pyrogram

docs/source/intro/setup.rst

@@ -0,0 +1,61 @@
+Project Setup
+=============
+
+We have just `installed Pyrogram`_. In this page we'll discuss what you need to do in order to set up a project with
+the library. Let's see how it's done.
+
+API Keys
+--------
+
+The very first step requires you to obtain a valid Telegram API key (API id/hash pair):
+
+#. 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 API key consists of two parts: **api_id** and **api_hash**.
+
+.. important::
+
+     The API key is personal and must be kept secret.
+
+.. note::
+
+    The API key is unique for each user, but defines a token for a Telegram *application* you are going to build. This
+    means that you are able to authorize multiple users (and bots too) to access the Telegram database through the
+    MTProto API by a single API key.
+
+Configuration
+-------------
+
+Having the API key from the `previous step <#api-keys>`_  in handy, we can now begin to configure a Pyrogram project.
+There are two ways to do so, and you can choose what fits better for you:
+
+-   First option (recommended): 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. This is the preferred method because
+    allows you to keep your credentials out of your code without having to deal with how to load them:
+
+    .. code-block:: ini
+
+        [pyrogram]
+        api_id = 12345
+        api_hash = 0123456789abcdef0123456789abcdef
+
+-   Alternatively, you can pass your API key to Pyrogram by simply using the *api_id* and *api_hash* parameters of the
+    Client class. This way you can have full control on how to store and load your credentials (e.g.:, you can load the
+    credentials from the environment variables and directly pass the values into Pyrogram):
+
+    .. code-block:: python
+
+        from pyrogram import Client
+
+        app = Client(
+            "my_account",
+            api_id=12345,
+            api_hash="0123456789abcdef0123456789abcdef"
+        )
+
+.. note::
+
+    To keep code snippets clean and concise, from now on it is assumed you are making use of the ``config.ini`` file,
+    thus, the *api_id* and *api_hash* parameters usage won't be shown anymore.
+
+.. _installed Pyrogram: install.html

docs/source/intro/start.rst

@@ -0,0 +1,45 @@
+Quick Start
+===========
+
+The next few steps serve as a quick start for all new Pyrogrammers that want to get something done as fast as possible!
+
+Get Pyrogram Real Fast
+----------------------
+
+1. Install Pyrogram with ``pip3 install -U pyrogram``.
+
+2. Get your own Telegram API key from https://my.telegram.org/apps.
+
+3. Open your best text editor and paste the following:
+
+    .. code-block:: python
+
+        from pyrogram import Client
+
+        api_id = 12345
+        api_hash = "0123456789abcdef0123456789abcdef"
+
+        with Client("my_account", api_id, api_hash) as app:
+            app.send_message("me", "Greetings from **Pyrogram**!")
+
+4. Replace *api_id* and *api_hash* values with your own.
+
+5. Save the file as ``pyro.py``.
+
+6. Run the script with ``python3 pyro.py``
+
+7. Follow the instructions on your terminal to login.
+
+8. Watch Pyrogram send a message to yourself.
+
+9. Join our `community <//t.me/pyrogramchat>`_.
+
+10. Say, "hi!".
+
+Enjoy the API
+-------------
+
+That was just a quick overview that barely scratched the surface!
+In the next few pages of the introduction, we'll take a much more in-depth look of what we have just done.
+
+Feeling eager? You can take a shortcut to `API Usage <../topics/usage.html>`_ and come back later to learn some more details.