Docs revamp. Part 6

docs/source/meta/faq.rst

@@ -20,17 +20,17 @@ C. It enables you to easily create custom applications for both user and bot ide
 `MTProto API`_ with the Python programming language.
 
 .. _Telegram: https://telegram.org
-.. _MTProto API: https://core.telegram.org/api#telegram-api
+.. _MTProto API: ../topics/mtproto-vs-botapi#what-is-the-mtproto-api
 
-What does the name mean?
+Where does the name come from?
-------------------------
+------------------------------
 
-The word "Pyrogram" is composed by **pyro**, which comes from the Greek word *πῦρ (pyr)*, meaning fire, and **gram**,
+The name "Pyrogram" is composed by **pyro**, which comes from the Greek word *πῦρ (pyr)*, meaning fire, and **gram**,
 from *Telegram*. The word *pyro* itself is built from *Python*, **py** for short, and the suffix **ro** to come up with
 the word *fire*, which also inspired the project logo.
 
-How old is the project?
+How old is Pyrogram?
------------------------
+--------------------
 
 Pyrogram was first released on December 12, 2017. The actual work on the framework began roughly three months prior the
 initial public release on `GitHub`_.
@@ -51,40 +51,15 @@ Why Pyrogram?
 - **Comprehensive**: Execute any `advanced action`_ an official client is able to do, and even more.
 
 .. _TgCrypto: https://github.com/pyrogram/tgcrypto
-.. _Smart Plugin: smart-plugins
+.. _Smart Plugin: ../topics/smart-plugins
-.. _advanced action: advanced-usage
+.. _advanced action: ../topics/advanced-usage
 
 What can MTProto do more than the Bot API?
 ------------------------------------------
 
-Here you can find a list of all the known advantages in using MTProto-based libraries (Pyrogram) instead of the official
+For a detailed answer, please refer to the `MTProto vs. Bot API`_ page.
-HTTP Bot API:
 
-- **Authorize both user and bot identities**: The Bot API only allows bot accounts.
+.. _MTProto vs. Bot API: ../topics/mtproto-vs-botapi
-
-- **Upload & download any file, up to 1500 MB each (~1.5 GB)**: The Bot API allows uploads and downloads of files only
-  up to 50 MB / 20 MB in size (respectively).
-
-- **Has less overhead due to direct connections to Telegram**: The Bot API uses an intermediate server to handle HTTP
-  requests before they are sent to the actual Telegram servers.
-
-- **Run multiple sessions at once, up to 10 per account (either bot or user)**: The Bot API intermediate server will
-  terminate any other session in case you try to use the same bot again in a parallel connection.
-
-- **Get information about any public chat by usernames, even if not a member**: The Bot API simply doesn't support this.
-
-- **Obtain information about any message existing in a chat using their ids**: The Bot API simply doesn't support this.
-
-- **Retrieve the whole chat members list of either public or private chats**: The Bot API simply doesn't support this.
-
-- **Receive extra updates, such as the one about a user name change**: The Bot API simply doesn't support this.
-
-- **Has more meaningful errors in case something went wrong**: The Bot API reports less detailed errors.
-
-- **Has much more detailed types and powerful methods**: The Bot API types often miss some useful information about
-  Telegram's type and some of the methods are limited as well.
-
-- **Get API version updates, and thus new features, sooner**: The Bot API is simply slower in implementing new features.
 
 Why do I need an API key for bots?
 ----------------------------------
@@ -126,7 +101,7 @@ fails or not:
 
 |bug report|
 
-.. _you need a proxy: proxy
+.. _you need a proxy: ../topics/proxy
 
 I keep getting PEER_ID_INVALID error!
 -------------------------------------------
@@ -150,12 +125,27 @@ Can I use the same file_id across different accounts?
 
 No, Telegram doesn't allow this.
 
-File ids are bound to a specific user/bot, and an attempt in using a foreign file id will result in errors such as
+File ids are personal and bound to a specific user/bot -- and an attempt in using a foreign file id will result in
-**[400 MEDIA_EMPTY]: The media is invalid**.
+errors such as **[400 MEDIA_EMPTY]: The media is invalid**.
 
 The only exception are stickers' file ids; you can use them across different accounts without any problem, like this
 one: ``CAADBAADyg4AAvLQYAEYD4F7vcZ43AI``.
 
+Can I use Bot API's file_ids in Pyrogram?
+-----------------------------------------
+
+Definitely! All file ids you might have taken from the Bot API are 100% compatible and re-usable in Pyrogram...
+
+...at least for now.
+
+Telegram is slowly changing some server's internals and it's doing it in such a way that file ids are going to break
+inevitably. Not only this, but it seems that the new, hypothetical, file ids could also possibly expire at anytime, thus
+losing the *persistence* feature.
+
+This change will most likely affect the official `Bot API <../topics/mtproto-vs-botapi#what-is-the-bot-api>`_  too
+(unless Telegram implements some workarounds server-side to keep backwards compatibility, which Pyrogram could in turn
+make use of) and we can expect a proper notice from Telegram.
+
 My account has been deactivated/limited!
 ----------------------------------------
 
@@ -184,13 +174,14 @@ About the License
 .. image:: https://www.gnu.org/graphics/lgplv3-with-text-154x68.png
     :align: left
 
-Pyrogram is free software and is currently licensed under the terms of the GNU Lesser General Public License v3 or later
+Pyrogram is free software and is currently licensed under the terms of the
-(LGPLv3+). In short: you may use, redistribute and/or modify it provided that modifications are described and licensed
+`GNU Lesser General Public License v3 or later (LGPLv3+)`_. In short: you may use, redistribute and/or modify it
-for free under LGPLv3+.
+provided that modifications are described and licensed for free under LGPLv3+.
 
 In other words: you can use and integrate Pyrogram into your own code --- either open source, under the same or a
 different licence or even proprietary --- without being required to release the source code of your own applications.
 However, any modifications to the library itself are required to be published for free under the same LGPLv3+ license.
 
+.. _GNU Lesser General Public License v3 or later (LGPLv3+): https://github.com/pyrogram/pyrogram/blob/develop/COPYING.lesser
 .. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md
 .. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md

docs/source/meta/glossary.rst

@@ -1,5 +1,5 @@
 Pyrogram Glossary
------------------
+=================
 
 This page contains a list of common words with brief explanations related to Pyrogram and, to some extent, Telegram in
 general. Some words may as well link to dedicated articles in case the topic is covered in a more detailed fashion.
@@ -18,6 +18,7 @@ general. Some words may as well link to dedicated articles in case the topic is
     API key
         A secret code used to authenticate and/or authorize a specific application to Telegram in order for it to
         control how the API is being used, for example, to prevent abuses of the API.
+        `More on API keys <../intro/setup#api-keys>`_.
 
     DC
         Also known as *data center*, is a place where lots of computer systems are housed and used together in order to
@@ -29,18 +30,21 @@ general. Some words may as well link to dedicated articles in case the topic is
 
     RPCError
         An error caused by an RPC which must be returned in place of the successful result in order to let the caller
-        know something went wrong.
+        know something went wrong. `More on RPCError <../start/errors>`_.
 
     MTProto
-        The name of the custom-made, open encryption protocol by Telegram, implemented in Pyrogram.
+        The name of the custom-made, open and encrypted protocol by Telegram, implemented in Pyrogram.
+        `More on MTProto <mtproto-vs-botapi>`_.
 
     MTProto API
         The Telegram main API Pyrogram makes use of, which is able to connect both users and normal bots to Telegram
-        using MTProto as application layer protocol and execute any method Telegram provides from its public schema.
+        using MTProto as application layer protocol and execute any method Telegram provides from its public TL-schema.
+        `More on MTProto API <mtproto-vs-botapi#what-is-the-mtproto-api>`_.
 
     Bot API
-        The `Telegram Bot API`_ that is able to only connect normal bots to Telegram using HTTP as application layer
+        The Telegram Bot API that is able to only connect normal bots to Telegram using HTTP as application layer
         protocol and allows to execute a subset of the main Telegram API.
+        `More on Bot API <mtproto-vs-botapi#what-is-the-bot-api>`_.
 
     Pyrogrammer
         A developer that uses Pyrogram to build Telegram applications.
@@ -61,12 +65,13 @@ general. Some words may as well link to dedicated articles in case the topic is
     Handler
         An object that wraps around a callback function that is *actually meant* to be registered into the framework,
         which will then be able to handle a specific kind of events, such as a new incoming message, for example.
+        `More on Handlers <../start/updates>`_
 
     Decorator
         Also known as *function decorator*, in Python, is a callable object that is used to modify another function.
-        Decorators in Pyrogram are used to automatically register callback functions for `handling updates`_.
+        Decorators in Pyrogram are used to automatically register callback functions for handling updates.
+        `More on Decorators <../start/updates#using-decorators>`_
 
-.. _Telegram Bot API: https://core.telegram.org/bots/api
 .. _handling updates: ../start/updates
 
 .. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md

docs/source/meta/powered-by.rst

@@ -0,0 +1,69 @@
+Powered by Pyrogram
+===================
+
+This is a collection of remarkable projects made with Pyrogram.
+
+.. A collection of Pyrojects :^)
+
+.. tip::
+
+    If you'd like to propose a project that's worth being listed here, feel free to open a `Feature Request`_.
+
+Projects Showcase
+-----------------
+
+`YTAudioBot <https://t.me/ytaudio>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| **A YouTube audio downloader on Telegram, serving over 200k MAU.**
+| --- by `Dan <https://t.me/haskell>`_
+
+- Main: https://t.me/ytaudiobot
+- Mirror: https://t.me/ytaudio_bot
+- Website: https://ytaudiobot.ml
+
+-----
+
+`Pyrogram Assistant <https://github.com/pyrogram/assistant>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| **The assistant bot that helps people with Pyrogram directly on Telegram**
+| --- by `Dan <https://t.me/haskell>`_
+
+- Bot: https://t.me/pyrogrambot
+- Source Code: https://github.com/pyrogram/assistant
+
+-----
+
+`PyroBot <https://git.colinshark.de/PyroBot/PyroBot>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| **A Telegram userbot based on Pyrogram**
+| --- by `Colin <https://t.me/ColinShark>`_
+
+- Source Code: https://git.colinshark.de/PyroBot/PyroBot
+
+-----
+
+`TgIntegration <https://github.com/JosXa/tgintegration>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| **Integration Test Library for Telegram Messenger Bots in Python**
+| --- by `JosXa <https://t.me/JosXa>`_
+
+- Source Code: https://github.com/JosXa/tgintegration
+
+-----
+
+`BotListBot <https://t.me/botlistt>`_
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| **A bot which partly uses Pyrogram to check if other bots are still alive**
+| --- by `JosXa <https://t.me/JosXa>`_
+
+- Source Code: https://github.com/JosXa/BotListBot
+
+-----
+
+.. _Feature Request: https://github.com/pyrogram/pyrogram/issues/new?labels=enhancement&template=feature_request.md
+

docs/source/meta/support-pyrogram.rst

@@ -0,0 +1,2 @@
+Support Pyrogram Development
+============================

docs/source/start/auth.rst

@@ -64,6 +64,6 @@ after the session name, which will be ``my_bot.session`` for the example below.
 
     app.run()
 
-.. _project is set up: setup.html
+.. _project is set up: ../intro/setup
 .. _Country Code: https://en.wikipedia.org/wiki/List_of_country_calling_codes
 .. _Bot Father: https://t.me/botfather

docs/source/topics/mtproto-vs-botapi.rst

@@ -0,0 +1,58 @@
+MTProto vs. Bot API
+===================
+
+Being Pyrogram an MTProto-based library, this very feature makes it already superior to, what is usually called, the
+official Bot API.
+
+What is the MTProto API?
+------------------------
+
+MTProto, took alone, is the name of the custom-made, open and encrypted communication protocol created by Telegram
+itself --- it's the only protocol used to exchange information between a client application and the actual Telegram
+servers.
+
+The MTProto **API** however, is what people, for convenience, call the main Telegram API as a whole. This API is able
+to authorize both users and bots and happens to be built on top of the MTProto encryption protocol by means of binary
+data serialized in a specific way, as described by the TL language, hence the correlation.
+
+What is the Bot API?
+--------------------
+
+The Bot API is an HTTP(S) interface for building normal bots. Bots are special accounts that are authorized via tokens
+instead of phone numbers. The Bot API is built yet again on top of the main Telegram API, but runs on an intermediate
+server application that in turn communicates with the actual Telegram servers using MTProto.
+
+.. figure:: https://i.imgur.com/C108qkX.png
+    :align: center
+
+Advantages of the MTProto API
+-----------------------------
+
+Here is a list of all the known advantages in using MTProto-based libraries (such as Pyrogram) instead of the official
+HTTP Bot API. Using Pyrogram you can:
+
+- **Authorize both user and bot identities**: The Bot API only allows bot accounts.
+
+- **Upload & download any file, up to 1500 MB each (~1.5 GB)**: The Bot API allows uploads and downloads of files only
+  up to 50 MB / 20 MB in size (respectively).
+
+- **Has less overhead due to direct connections to Telegram**: The Bot API uses an intermediate server to handle HTTP
+  requests before they are sent to the actual Telegram servers.
+
+- **Run multiple sessions at once, up to 10 per account (either bot or user)**: The Bot API intermediate server will
+  terminate any other session in case you try to use the same bot again in a parallel connection.
+
+- **Get information about any public chat by usernames, even if not a member**: The Bot API simply doesn't support this.
+
+- **Obtain information about any message existing in a chat using their ids**: The Bot API simply doesn't support this.
+
+- **Retrieve the whole chat members list of either public or private chats**: The Bot API simply doesn't support this.
+
+- **Receive extra updates, such as the one about a user name change**: The Bot API simply doesn't support this.
+
+- **Has more meaningful errors in case something went wrong**: The Bot API reports less detailed errors.
+
+- **Has much more detailed types and powerful methods**: The Bot API types often miss some useful information about
+  Telegram's type and some of the methods are limited as well.
+
+- **Get API version updates, and thus new features, sooner**: The Bot API is simply slower in implementing new features.