Enhance documentation

readthedocs/extra/advanced-usage/accessing-the-full-api.rst

@@ -4,6 +4,12 @@
 Accessing the Full API
 ======================
 
+.. important::
+
+    While you have access to this, you should always use the friendly
+    methods listed on :ref:`telethon-package` unless you have a better
+    reason not to, like a method not existing or you wanting more control.
+
 
 The ``TelegramClient`` doesn't offer a method for every single request
 the Telegram API supports. However, it's very simple to *call* or *invoke*

readthedocs/extra/basic/getting-started.rst

@@ -65,6 +65,8 @@ Basic Usage
 
    **More details**: :ref:`telegram-client`
 
+   See :ref:`telethon-package` for all available friendly methods.
+
 
 Handling Updates
 ****************

readthedocs/extra/basic/telegram-client.rst

@@ -10,8 +10,10 @@ Introduction
 
 .. note::
 
-    Check the :ref:`telethon-package` if you're looking for the methods
-    reference instead of this tutorial.
+    Make sure to use the friendly methods described in :ref:`telethon-package`!
+    This section is just an introduction to using the client, but all the
+    available methods are in the :ref:`telethon-package` reference, including
+    detailed descriptions to what they do.
 
 The ``TelegramClient`` is the central class of the library, the one
 you will be using most of the time. For this reason, it's important

readthedocs/extra/examples/chats-and-channels.rst

@@ -94,12 +94,13 @@ the hash of said channel or group.
 Retrieving all chat members (channels too)
 ******************************************
 
-You can use
-`client.get_participants <telethon.telegram_client.TelegramClient.get_participants>`
-to retrieve the participants (click it to see the relevant parameters).
-Most of the time you will just need ``client.get_participants(entity)``.
+.. note::
+
+    Use the `telethon.telegram_client.TelegramClient.iter_participants`
+    friendly method instead unless you have a better reason not to!
+
+    This method will handle different chat types for you automatically.
 
-This is what said method is doing behind the scenes as an example.
 
 In order to get all the members from a mega-group or channel, you need
 to use :tl:`GetParticipantsRequest`. As we can see it needs an

readthedocs/extra/examples/projects-using-telethon.rst

@@ -12,6 +12,7 @@ the library.
     `issue 744 <https://github.com/LonamiWebs/Telethon/issues/744>`_
     so it can be included in the next revision of the documentation!
 
+.. _projects-telegram-export:
 
 telegram-export
 ***************
@@ -22,6 +23,7 @@ telegram-export
 A tool to download Telegram data (users, chats, messages, and media)
 into a database (and display the saved data).
 
+.. _projects-mautrix-telegram:
 
 mautrix-telegram
 ****************
@@ -31,6 +33,7 @@ mautrix-telegram
 
 A Matrix-Telegram hybrid puppeting/relaybot bridge.
 
+.. _projects-telegramtui:
 
 TelegramTUI
 ***********

readthedocs/extra/examples/users.rst

@@ -65,6 +65,6 @@ through :tl:`UploadProfilePhoto`:
 
         from telethon.tl.functions.photos import UploadProfilePhotoRequest
 
-        client(functions.photos.UploadProfilePhotoRequest(
+        client(UploadProfilePhotoRequest(
             client.upload_file('/path/to/some/file')
         ))

readthedocs/extra/examples/working-with-messages.rst

@@ -11,11 +11,14 @@ Working with messages
 Forwarding messages
 *******************
 
-This request is available as a friendly method through
-`client.forward_messages <telethon.telegram_client.TelegramClient.forward_messages>`,
-and can be used like shown below:
+.. note::
 
-    .. code-block:: python
+    Use the `telethon.telegram_client.TelegramClient.forward_messages`
+    friendly method instead unless you have a better reason not to!
+
+    This method automatically accepts either a single message or many of them.
+
+.. code-block:: python
 
         # If you only have the message IDs
         client.forward_messages(
@@ -51,6 +54,14 @@ too, if that's all you have.
 Searching Messages
 *******************
 
+.. note::
+
+    Use the `telethon.telegram_client.TelegramClient.iter_messages`
+    friendly method instead unless you have a better reason not to!
+
+    This method has ``search`` and ``filter`` parameters that will
+    suit your needs.
+
 Messages are searched through the obvious :tl:`SearchRequest`, but you may run
 into issues_. A valid example would be:
 
@@ -71,7 +82,8 @@ into issues_. A valid example would be:
             limit=10,       # How many results
             max_id=0,       # Maximum message ID
             min_id=0,       # Minimum message ID
-            from_id=None    # Who must have sent the message (peer)
+            from_id=None,   # Who must have sent the message (peer)
+            hash=0          # Special number to return nothing on no-change
         ))
 
 It's important to note that the optional parameter ``from_id`` could have

readthedocs/index.rst

@@ -18,6 +18,9 @@ when you upgrade!
    If you're new here, you want to read :ref:`getting-started`. If you're
    looking for the method reference, you should check :ref:`telethon-package`.
 
+   The mentioned :ref:`telethon-package` is an important section and it
+   contains the friendly methods that **you should use** most of the time.
+
 
 What is this?
 *************

readthedocs/telethon.events.rst

@@ -47,6 +47,13 @@ so all the methods in it can be used from any event builder/event instance.
     :undoc-members:
     :show-inheritance:
 
+
+.. automodule:: telethon.events.raw
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 .. automodule:: telethon.events
     :members:
     :undoc-members: