From b6f508711aff07b7a35f9f271514c4385bb4c2f4 Mon Sep 17 00:00:00 2001 From: Dan <14043624+delivrance@users.noreply.github.com> Date: Thu, 27 Jun 2019 23:16:21 +0200 Subject: [PATCH] Many minor documentation enhancements --- docs/source/api/client.rst | 6 +++++- docs/source/api/decorators.rst | 2 +- docs/source/api/handlers.rst | 3 --- docs/source/api/methods.rst | 2 +- docs/source/api/types.rst | 2 +- docs/source/index.rst | 2 +- docs/source/start/updates.rst | 12 +++++++----- docs/source/topics/storage-engines.rst | 2 +- docs/source/topics/use-filters.rst | 4 ++-- 9 files changed, 19 insertions(+), 16 deletions(-) diff --git a/docs/source/api/client.rst b/docs/source/api/client.rst index d1b8c4b0..d28b7f61 100644 --- a/docs/source/api/client.rst +++ b/docs/source/api/client.rst @@ -1,7 +1,11 @@ Pyrogram Client =============== -This is the Client class. It exposes high-level methods for an easy access to the API. +You have entered the API Reference section where you can find detailed information about Pyrogram's API. The main Client +class, all available methods and types, filters, handlers, decorators and bound-methods detailed descriptions can be +found starting from this page. + +This page is about the Client class, which exposes high-level methods for an easy access to the API. .. code-block:: python :emphasize-lines: 1-3 diff --git a/docs/source/api/decorators.rst b/docs/source/api/decorators.rst index ff31cb27..fd397cc4 100644 --- a/docs/source/api/decorators.rst +++ b/docs/source/api/decorators.rst @@ -6,7 +6,7 @@ deserve a dedicated page. Decorators are able to register callback functions for handling updates in a much easier and cleaner way compared to :doc:`Handlers `; they do so by instantiating the correct handler and calling -:meth:`~pyrogram.Client.add_handler`, automatically. All you need to do is adding the decorators on top of your +:meth:`~pyrogram.Client.add_handler` automatically. All you need to do is adding the decorators on top of your functions. .. code-block:: python diff --git a/docs/source/api/handlers.rst b/docs/source/api/handlers.rst index f91dd3d5..1ae0961b 100644 --- a/docs/source/api/handlers.rst +++ b/docs/source/api/handlers.rst @@ -2,10 +2,7 @@ Update Handlers =============== Handlers are used to instruct Pyrogram about which kind of updates you'd like to handle with your callback functions. - For a much more convenient way of registering callback functions have a look at :doc:`Decorators ` instead. -In case you decided to manually create a handler, use :class:`~pyrogram.Client.add_handler` to register -it. .. code-block:: python :emphasize-lines: 1, 10 diff --git a/docs/source/api/methods.rst b/docs/source/api/methods.rst index 2a08b37f..0cd7700f 100644 --- a/docs/source/api/methods.rst +++ b/docs/source/api/methods.rst @@ -1,7 +1,7 @@ Available Methods ================= -All Pyrogram methods listed here are bound to a :class:`~pyrogram.Client` instance. +This page is about Pyrogram methods. All the methods listed here are bound to a :class:`~pyrogram.Client` instance. .. code-block:: python :emphasize-lines: 6 diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst index 644f8bb2..f91e4f58 100644 --- a/docs/source/api/types.rst +++ b/docs/source/api/types.rst @@ -1,7 +1,7 @@ Available Types =============== -All Pyrogram types listed here are accessible through the main package directly. +This page is about Pyrogram types. All types listed here are accessible through the main package directly. .. code-block:: python :emphasize-lines: 1 diff --git a/docs/source/index.rst b/docs/source/index.rst index 66722690..682c883c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -28,8 +28,8 @@ Welcome to Pyrogram api/bound-methods api/handlers api/decorators - api/filters api/errors + api/filters .. toctree:: :hidden: diff --git a/docs/source/start/updates.rst b/docs/source/start/updates.rst index 9b0a5a32..056fcb3d 100644 --- a/docs/source/start/updates.rst +++ b/docs/source/start/updates.rst @@ -45,7 +45,9 @@ arrives: app.run() -#. Let's examine these four new pieces. First one: a callback function we defined which accepts two arguments - +Let's examine these four new pieces. + +#. A callback function we defined which accepts two arguments - *(client, message)*. This will be the function that gets executed every time a new message arrives and Pyrogram will call that function by passing the client instance and the new message instance as argument. @@ -54,14 +56,14 @@ arrives: def my_function(client, message): print(message) -#. Second one: the :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must - only handle updates that are in form of a :class:`~pyrogram.Message`: +#. The :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must only handle + updates that are in form of a :class:`~pyrogram.Message`: .. code-block:: python my_handler = MessageHandler(my_function) -#. Third: the method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let +#. The method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let Pyrogram know it needs to be taken into consideration when new updates arrive and the internal dispatching phase begins. @@ -69,7 +71,7 @@ arrives: app.add_handler(my_handler) -#. Last one, the :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and +#. The :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and a special method :meth:`~pyrogram.Client.idle` that keeps your main scripts alive until you press ``CTRL+C``; the client will be automatically stopped after that. diff --git a/docs/source/topics/storage-engines.rst b/docs/source/topics/storage-engines.rst index a161e50f..44b4afa6 100644 --- a/docs/source/topics/storage-engines.rst +++ b/docs/source/topics/storage-engines.rst @@ -95,5 +95,5 @@ engine to properly work as intended. But, why is the session string so long? Can't it be shorter? No, it can't. The session string already packs the bare minimum data Pyrogram needs to successfully reconnect to an authorized session, and the 2048-bits auth key is the major -contributor to the overall length. Needless to repeat that this string, as well as any other session storage, represent +contributor to the overall length. Needless to say that this string, as well as any other session storage, represent strictly personal data. Keep them safe. diff --git a/docs/source/topics/use-filters.rst b/docs/source/topics/use-filters.rst index d481b393..de7a35a8 100644 --- a/docs/source/topics/use-filters.rst +++ b/docs/source/topics/use-filters.rst @@ -1,8 +1,8 @@ Using Filters ============= -So far we've seen how to register a callback function that executes every time a specific update comes from the server, -but there's much more than that to come. +So far we've seen :doc:`how to register a callback function <../start/updates>` that executes every time a specific update +comes from the server, but there's much more than that to come. Here we'll discuss about :class:`~pyrogram.Filters`. Filters enable a fine-grain control over what kind of updates are allowed or not to be passed in your callback functions, based on their inner details.