Docs revamp. Part 3

compiler/docs/compiler.py

@@ -21,7 +21,7 @@ import os
 import shutil
 
 HOME = "compiler/docs"
-DESTINATION = "docs/source"
+DESTINATION = "docs/source/telegram"
 
 FUNCTIONS_PATH = "pyrogram/api/functions"
 TYPES_PATH = "pyrogram/api/types"
@@ -129,6 +129,6 @@ if "__main__" == __name__:
     FUNCTIONS_PATH = "../../pyrogram/api/functions"
     TYPES_PATH = "../../pyrogram/api/types"
     HOME = "."
-    DESTINATION = "../../docs/source"
+    DESTINATION = "../../docs/source/telegram"
 
     start()

docs/source/api/client.rst

@@ -0,0 +1,7 @@
+Pyrogram Client
+===============
+
+The :class:`Client <pyrogram.Client>` is the main class. It exposes easy-to-use methods that are named
+after the well established Telegram Bot API methods, thus offering a familiar look to Bot developers.
+
+.. autoclass:: pyrogram.Client()

docs/source/api/errors.rst

@@ -1,5 +1,5 @@
-Errors
-======
+RPC Errors
+==========
 
 All the Pyrogram errors listed here live inside the ``errors`` sub-package.
 

docs/source/api/filters.rst

@@ -1,5 +1,5 @@
-Filters
-=======
+Update Filters
+==============
 
 .. autoclass:: pyrogram.Filters
     :members:

docs/source/core/client.rst

@@ -1,12 +0,0 @@
-Pyrogram
-========
-
-In this section you can find a detailed description of the Pyrogram package and its API.
-
-:class:`Client <pyrogram.Client>` is the main class. It exposes easy-to-use methods that are named
-after the well established Telegram Bot API methods, thus offering a familiar look to Bot developers.
-
-Client
-------
-
-.. autoclass:: pyrogram.Client()

docs/source/index.rst

@@ -54,26 +54,54 @@ Welcome to Pyrogram
 
     app.run()
 
-**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and C.
-It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the `MTProto API`_.
+**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
+C. It enables you to easily create custom apps using both user and bot identities (bot API alternative) via the
+`MTProto API`_.
 
-How the documentation is organized
+.. _Telegram: https://telegram.org
+.. _MTProto API: https://core.telegram.org/api#telegram-api
+
+How the Documentation is Organized
 ----------------------------------
 
-Contents are organized into self-contained topics and can be accessed from the sidebar, or by following them in order
-using the Next button at the end of each page.
+Contents are organized into self-contained topics and can be all accessed from the sidebar, or by following them in
+order using the Next button at the end of each page. Here below you can find a list of the most relevant pages.
 
-Relevant Pages
-^^^^^^^^^^^^^^
+Getting Started
+^^^^^^^^^^^^^^^
 
-- `Quick Start`_ - Concise steps to get you started as fast as possible.
-- `API Usage`_ - Guide on how to use Pyrogram's API.
-- `Update Handling`_ - Guide on how to handle Telegram updates.
-- Client_ - Reference details about the Client class.
-- Types_ - All the available Pyrogram types.
-- Methods_ - All the available Pyrogram methods.
+- `Quick Start`_ - Overview to get you started as fast as possible.
+- `Calling Methods`_ - How to use Pyrogram's API.
+- `Handling Updates`_ - How to handle Telegram updates.
+- `Error Handling`_ - How to handle API errors correctly.
 
-**To get started, press the Next button**
+.. _Quick Start: intro/start
+.. _Calling Methods: start/invoking
+.. _Handling Updates: start/updates
+.. _Error Handling: start/errors
+
+API Reference
+^^^^^^^^^^^^^
+- `Client Class`_ - Details about the Client class.
+- `Available Methods`_ - A list of available high-level methods.
+- `Available Types`_ - A list of available high-level types.
+
+.. _Client Class: core/client
+.. _Available Methods: core/methods
+.. _Available Types: core/types
+
+Topics
+^^^^^^
+
+- `Smart Plugins`_ - How to modularize your application.
+- `Advanced Usage`_ - How to use Telegram's raw API.
+- `Release Notes`_ - Release notes for Pyrogram releases.
+- `Pyrogram FAQ`_ - Answers to common Pyrogram questions.
+
+.. _Smart Plugins: topics/smart-plugins
+.. _Advanced Usage: topics/advanced-usage
+.. _Release Notes: topics/releases
+.. _Pyrogram FAQ: topics/faq
 
 .. toctree::
     :hidden:
@@ -82,55 +110,51 @@ Relevant Pages
     intro/start
     intro/install
     intro/setup
-    intro/auth
 
 .. toctree::
     :hidden:
-    :caption: Topic Guides
+    :caption: Getting Started
 
-    topics/usage
-    topics/update-handling
-    topics/using-filters
-    topics/more-on-updates
-    topics/configuration-file
-    topics/smart-plugins
-    topics/auto-authorization
-    topics/customize-sessions
-    topics/tgcrypto
-    topics/text-formatting
-    topics/socks5-proxy
-    topics/bots-interaction
-    topics/error-handling
-    topics/test-servers
-    topics/advanced-usage
-    topics/voice-calls
-    topics/changelog
+    intro/auth
+    start/invoking
+    start/updates
+    start/errors
 
 .. toctree::
     :hidden:
     :caption: API Reference
 
-    core/client
-    core/types
-    core/methods
-    core/handlers
-    core/decorators
-    core/filters
-    core/errors
+    api/client
+    api/methods
+    api/types
+    api/handlers
+    api/decorators
+    api/filters
+    api/errors
+
+.. toctree::
+    :hidden:
+    :caption: Topic Guides
+
+    topics/filters
+    topics/more-on-updates
+    topics/config-file
+    topics/smart-plugins
+    topics/auto-auth
+    topics/session-settings
+    topics/tgcrypto
+    topics/text-formatting
+    topics/proxy
+    topics/bots-interaction
+    topics/test-servers
+    topics/advanced-usage
+    topics/voice-calls
+    topics/releases
+    topics/faq
 
 .. toctree::
     :hidden:
     :caption: Telegram API
 
-    functions/index
-    types/index
-
-.. _Telegram: https://telegram.org
-.. _TgCrypto: https://docs.pyrogram.ml/resources/TgCrypto
-.. _MTProto API: https://core.telegram.org/api#telegram-api
-.. _Quick Start: intro/start.html
-.. _API Usage: topics/usage.html
-.. _Update Handling: topics/update-handling.html
-.. _Client: core/client.html
-.. _Types: core/types.html
-.. _Methods: core/methods
+    telegram/functions/index
+    telegram/types/index

docs/source/intro/start.rst

@@ -32,7 +32,7 @@ Get Pyrogram Real Fast
 
 8. Watch Pyrogram send a message to yourself.
 
-9. Join our `community <//t.me/pyrogramchat>`_.
+9. Join our `community`_.
 
 10. Say, "hi!".
 
@@ -42,4 +42,8 @@ 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.
+Feeling eager? You can take a shortcut to `Calling Methods`_ and come back later to learn some more
+details.
+
+.. _community: //t.me/pyrogramchat
+.. _Calling Methods: ../start/invoking

docs/source/start/errors.rst

@@ -16,8 +16,7 @@ There are many errors that Telegram could return, but they all fall in one of th
 
 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.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.
+in the ``unknown_errors.txt`` file. Users are invited to report these unknown errors.
 
 Examples
 --------

docs/source/start/invoking.rst

@@ -1,14 +1,10 @@
-API Usage
-=========
+Calling Methods
+===============
 
-At this point, we have successfully `installed Pyrogram`_ and authorized_ our account and we are now pointing towards
-the core of the library. It's time to start playing with the API!
+At this point, we have successfully `installed Pyrogram`_ and authorized_ our account; we are now pointing towards the
+core of the library. It's time to start playing with the API!
 
-Make API Method Calls
----------------------
-
-Making API method calls with Pyrogram is very simple.
-Here's an example we are going to examine:
+Making API method calls with Pyrogram is very simple. Here's an example we are going to examine:
 
 .. code-block:: python
 

docs/source/start/updates.rst

@@ -1,12 +1,12 @@
-Update Handling
-===============
+Handling Updates
+================
 
 Calling `API methods`_ sequentially is cool, but how to react when, for example, a new message arrives? This page deals
-with updates and how to handle them in Pyrogram. Let's have a look at how they work.
+with updates and how to handle such events in Pyrogram. Let's have a look at how they work.
 
-First, let's define what are these updates. Updates are simply events that happen in your Telegram account (incoming
-messages, new members join, button presses, etc...), which are meant to notify you about a new specific state that
-changed. These updates are handled by registering one or more callback functions in your app using
+First, let's define what are these updates. As hinted already, updates are simply events that happen in your Telegram
+account (incoming messages, new members join, button presses, etc...), which are meant to notify you about a new
+specific state that changed. These updates are handled by registering one or more callback functions in your app using
 `Handlers <../pyrogram/Handlers.html>`_.
 
 Each handler deals with a specific event and once a matching update arrives from Telegram, your registered callback

docs/source/topics/changelog.rst

@@ -1,11 +0,0 @@
-Changelog
-=========
-
-Currently, all Pyrogram release notes live inside the GitHub repository web page:
-https://github.com/pyrogram/pyrogram/releases
-
-(You will be automatically redirected in 10 seconds.)
-
-.. raw:: html
-
-    <meta http-equiv="refresh" content="10; URL=https://github.com/pyrogram/pyrogram/releases"/>

docs/source/topics/faq.rst

@@ -0,0 +1,107 @@
+Pyrogram FAQ
+============
+
+This FAQ page provides answers to common questions about Pyrogram and, to some extent, Telegram in general.
+
+.. contents:: Contents
+    :backlinks: none
+    :local:
+
+What is Pyrogram?
+-----------------
+
+**Pyrogram** is an elegant, easy-to-use Telegram_ client library and framework written from the ground up in Python and
+C. It enables you to easily create custom applications using both user and bot identities (bot API alternative) via the
+`MTProto API`_ with the Python programming language.
+
+.. _Telegram: https://telegram.org
+.. _MTProto API: https://core.telegram.org/api#telegram-api
+
+What does "Pyrogram" mean?
+--------------------------
+
+The word "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 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`_.
+
+.. _GitHub: <https://github.com/pyrogram/pyrogram>
+
+Why do I need an API key for bots?
+----------------------------------
+
+Requests against the official bot API endpoint are made via JSON/HTTP, but are handled by a backend application that
+implements the MTProto protocol -- just like Pyrogram -- and uses its own API key, which is always required, but hidden
+to the public.
+
+.. figure:: https://i.imgur.com/C108qkX.png
+    :align: center
+
+Using MTProto is the only way to communicate with the actual Telegram servers, and the main API requires developers to
+identify applications by means of a unique key; the bot token identifies a bot as a user and replaces the user's phone
+number only.
+
+I started a client but nothing happens!
+---------------------------------------
+
+If you are connecting from Russia, China or Iran `you need a proxy`_, because Telegram could be partially or
+totally blocked in those countries.
+
+Another possible cause might be network issues, either yours or Telegram's. To confirm this, add the following code on
+the top of your script and run it again. You should see some error mentioning a socket timeout or an unreachable network
+in a bunch of seconds:
+
+.. code-block:: python
+
+    import logging
+    logging.basicConfig(level=logging.INFO)
+
+|bug report|
+
+.. _you need a proxy: proxy
+
+I keep getting [400 PEER_ID_INVALID] error!
+-------------------------------------------
+
+The error in question is ``[400 PEER_ID_INVALID]: The id/access_hash combination is invalid``, and could mean several
+things:
+
+- The chat id you tried to use is simply wrong, double check it.
+- The chat id refers to a group or channel you are not a member of.
+- The chat id refers to a user you have't seen yet (from contacts, groups in common, forwarded messages or private
+  chats).
+
+|bug report|
+
+.. |bug report| replace::
+
+    **Note:** If you really believe this should not happen, kindly open a `Bug Report`_.
+
+.. _Bug Report: https://github.com/pyrogram/pyrogram/issues/new?labels=bug&template=bug_report.md
+
+My account has been deactivated/limited!
+----------------------------------------
+
+First of all, you should understand that Telegram wants to be a safe place for people to stay in, and to pursue this
+goal there are automatic protection systems running to prevent flood and spam, as well as a moderation team of humans
+who reviews reports.
+
+**Pyrogram is a tool at your commands; it only does what you tell it to do, the rest is up to you.**
+
+Having said that, here's how a list of what Telegram definitely doesn't like:
+
+- Flood, abusing the API.
+- Spam, sending unsolicited messages or adding people to unwanted groups and channels.
+- Virtual/VoIP and cheap real numbers, because they are relatively easy to get and likely used for spam/flood.
+
+However, you might be right, and your account was deactivated/limited without any reason. This could happen because of
+mistakes by either the automatic systems or a moderator. In such cases you can kindly email Telegram at
+recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_.
+
+.. _@smstelegram: https://twitter.com/smstelegram
+.. _this form: https://telegram.org/support

docs/source/topics/releases.rst

@@ -0,0 +1,13 @@
+Release Notes
+=============
+
+Release notes for Pyrogram releases will describe what's new in each version, and will also make you aware of any
+backwards-incompatible changes made in that version.
+
+When upgrading to a new version of Pyrogram, you will need to check all the breaking changes in order to find
+incompatible code in your application, but also to take advantage of new features and improvements.
+
+.. note::
+
+    Currently, all Pyrogram release notes live inside the GitHub repository web page:
+    https://github.com/pyrogram/pyrogram/releases.

docs/source/topics/session-settings.rst

@@ -1,5 +1,5 @@
-Customize Sessions
-==================
+Session Settings
+================
 
 As you may probably know, Telegram allows users (and bots) having more than one session (authorizations) registered
 in the system at the same time.
@@ -8,7 +8,6 @@ Briefly explaining, sessions are simply new logins in your account. They can be
 app (or by invoking `GetAuthorizations <../functions/account/GetAuthorizations.html>`_ with Pyrogram). They store some
 useful information such as the client who's using them and from which country and IP address.
 
-
 .. figure:: https://i.imgur.com/lzGPCdZ.png
     :width: 70%
     :align: center

docs/source/topics/text-formatting.rst

@@ -11,7 +11,7 @@ Beside bold, italic, and pre-formatted code, **Pyrogram does also support inline
 Markdown Style
 --------------
 
-To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdown" in the *parse_mode* field when using
+To use this mode, pass "markdown" in the *parse_mode* field when using
 :obj:`send_message() <pyrogram.Client.send_message>`. Use the following syntax in your message:
 
 .. code-block:: text
@@ -34,8 +34,8 @@ To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdow
 HTML Style
 ----------
 
-To use this mode, pass :obj:`HTML <pyrogram.ParseMode.HTML>` or "html" in the *parse_mode* field when using
-:obj:`send_message() <pyrogram.Client.send_message>`. The following tags are currently supported:
+To use this mode, pass "html" in the *parse_mode* field when using :obj:`send_message() <pyrogram.Client.send_message>`.
+The following tags are currently supported:
 
 .. code-block:: text
 

pyrogram/client/client.py

@@ -60,7 +60,7 @@ log = logging.getLogger(__name__)
 
 
 class Client(Methods, BaseClient):
-    """This class represents a Client, the main mean for interacting with Telegram.
+    """This class represents a Client, the main means for interacting with Telegram.
     It exposes bot-like methods for an easy access to the API as well as a simple way to
     invoke every single Telegram API method available.
 
@@ -438,7 +438,7 @@ class Client(Methods, BaseClient):
         self.stop()
 
     def run(self):
-        """Use this method as a convenience shortcut to automatically start the Client and idle the main script.
+        """Use this method to start the Client and automatically idle the main script.
 
         This is a convenience method that literally just calls :meth:`start` and :meth:`idle`. It makes running a client
         less verbose, but is not suitable in case you want to run more than one client in a single main script,

setup.py

@@ -48,7 +48,7 @@ def get_readme():
 class Clean(Command):
     DIST = ["./build", "./dist", "./Pyrogram.egg-info"]
     API = ["pyrogram/api/errors/exceptions", "pyrogram/api/functions", "pyrogram/api/types", "pyrogram/api/all.py"]
-    DOCS = ["docs/source/functions", "docs/source/types", "docs/build"]
+    DOCS = ["docs/source/telegram", "docs/build"]
     ALL = DIST + API + DOCS
 
     description = "Clean generated files"