Update documentation with intersphinx and better summaries

readthedocs/basic/updates.rst

@@ -79,7 +79,7 @@ with a ``'hi!'`` message.
 .. note::
 
     Event handlers **must** be ``async def``. After all,
-    Telethon is an asynchronous library based on asyncio_,
+    Telethon is an asynchronous library based on `asyncio`,
     which is a safer and often faster approach to threads.
 
     You **must** ``await`` all method calls that use
@@ -157,5 +157,3 @@ Make sure you understand the code seen here before continuing!
 As a rule of thumb, remember that new message events behave just
 like message objects, so you can do with them everything you can
 do with a message object.
-
-.. _asyncio: https://docs.python.org/3/library/asyncio.html

readthedocs/concepts/asyncio.rst

@@ -10,11 +10,11 @@ Mastering asyncio
 What's asyncio?
 ===============
 
-asyncio_ is a Python 3's built-in library. This means it's already installed if
+`asyncio` is a Python 3's built-in library. This means it's already installed if
 you have Python 3. Since Python 3.5, it is convenient to work with asynchronous
 code. Before (Python 3.4) we didn't have ``async`` or ``await``, but now we do.
 
-asyncio_ stands for *Asynchronous Input Output*. This is a very powerful
+`asyncio` stands for *Asynchronous Input Output*. This is a very powerful
 concept to use whenever you work IO. Interacting with the web or external
 APIs such as Telegram's makes a lot of sense this way.
 
@@ -24,7 +24,7 @@ Why asyncio?
 
 Asynchronous IO makes a lot of sense in a library like Telethon.
 You send a request to the server (such as "get some message"), and
-thanks to asyncio_, your code won't block while a response arrives.
+thanks to `asyncio`, your code won't block while a response arrives.
 
 The alternative would be to spawn a thread for each update so that
 other code can run while the response arrives. That is *a lot* more
@@ -234,7 +234,7 @@ the client:
 
 Generally, **you don't need threads** unless you know what you're doing.
 Just create another task, as shown above. If you're using the Telethon
-with a library that uses threads, you must be careful to use ``threading.Lock``
+with a library that uses threads, you must be careful to use `threading.Lock`
 whenever you use the client, or enable the compatible mode. For that, see
 :ref:`compatibility-and-convenience`.
 
@@ -254,7 +254,7 @@ client.run_until_disconnected() blocks!
 
 All of what `client.run_until_disconnected()
 <telethon.client.updates.UpdateMethods.run_until_disconnected>` does is
-run the asyncio_'s event loop until the client is disconnected. That means
+run the `asyncio`'s event loop until the client is disconnected. That means
 *the loop is running*. And if the loop is running, it will run all the tasks
 in it. So if you want to run *other* code, create tasks for it:
 
@@ -274,9 +274,10 @@ in it. So if you want to run *other* code, create tasks for it:
 This creates a task for a clock that prints the time every second.
 You don't need to use `client.run_until_disconnected()
 <telethon.client.updates.UpdateMethods.run_until_disconnected>` either!
-You just need to make the loop is running, somehow. ``asyncio.run_forever``
-and ``asyncio.run_until_complete`` can also be used to run the loop, and
-Telethon will be happy with any approach.
+You just need to make the loop is running, somehow. `loop.run_forever()
+<asyncio.loop.run_forever()>` and `loop.run_until_complete()
+<asyncio.loop.run_until_complete>` can also be used to run
+the loop, and Telethon will be happy with any approach.
 
 Of course, there are better tools to run code hourly or daily, see below.
 
@@ -285,7 +286,7 @@ What else can asyncio do?
 =========================
 
 Asynchronous IO is a really powerful tool, as we've seen. There are plenty
-of other useful libraries that also use asyncio_ and that you can integrate
+of other useful libraries that also use `asyncio` and that you can integrate
 with Telethon.
 
 * `aiohttp <https://github.com/aio-libs/aiohttp>`_ is like the infamous
@@ -314,7 +315,7 @@ you can run requests in parallel:
 This code will get the 10 last messages from `@TelethonChat
 <https://t.me/TelethonChat>`_, send one to `@TelethonOfftopic
 <https://t.me/TelethonOfftopic>`_, and also download the profile
-photo of the main group. asyncio_ will run all these three tasks
+photo of the main group. `asyncio` will run all these three tasks
 at the same time. You can run all the tasks you want this way.
 
 A different way would be:
@@ -355,8 +356,6 @@ Where can I read more?
 ======================
 
 `Check out my blog post
-<https://lonamiwebs.github.io/blog/asyncio/>`_ about asyncio_, which
+<https://lonamiwebs.github.io/blog/asyncio/>`_ about `asyncio`, which
 has some more examples and pictures to help you understand what happens
 when the loop runs.
-
-.. _asyncio: https://docs.python.org/3/library/asyncio.html

readthedocs/concepts/updates.rst

@@ -158,12 +158,12 @@ Understanding asyncio
 =====================
 
 
-With ``asyncio``, the library has several tasks running in the background.
+With `asyncio`, the library has several tasks running in the background.
 One task is used for sending requests, another task is used to receive them,
 and a third one is used to handle updates.
 
 To handle updates, you must keep your script running. You can do this in
-several ways. For instance, if you are *not* running ``asyncio``'s event
+several ways. For instance, if you are *not* running `asyncio`'s event
 loop, you should use `client.run_until_disconnected
 <telethon.client.updates.UpdateMethods.run_until_disconnected>`:
 

readthedocs/conf.py

@@ -40,9 +40,14 @@ tl_ref_url = 'https://tl.telethon.dev'
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
     'custom_roles'
 ]
 
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None)
+}
+
 # Change the default role so we can avoid prefixing everything with :obj:
 default_role = "py:obj"
 

readthedocs/examples/chats-and-channels.rst

@@ -195,11 +195,11 @@ banned rights of a user through :tl:`EditBannedRequest` and its parameter
     client(EditBannedRequest(channel, user, rights))
 
 
-You can also use a ``datetime`` object for ``until_date=``, or even a
-Unix timestamp. Note that if you ban someone for less than 30 seconds
-or for more than 366 days, Telegram will consider the ban to actually
-last forever. This is officially documented under
-https://core.telegram.org/bots/api#restrictchatmember.
+You can use a `datetime.datetime` object for ``until_date=``,
+a `datetime.timedelta` or even a Unix timestamp. Note that if you ban
+someone for less than 30 seconds or for more than 366 days, Telegram
+will consider the ban to actually last forever. This is officially
+documented under https://core.telegram.org/bots/api#restrictchatmember.
 
 
 Kicking a member

readthedocs/misc/changelog.rst

@@ -1152,7 +1152,7 @@ reasons. But there's one more surprise!
 
 There is a new magic ``telethon.sync`` module to let you use **all** the
 methods in the :ref:`TelegramClient <telethon-client>` (and the types returned
-from its functions) in a synchronous way, while using ``asyncio`` behind
+from its functions) in a synchronous way, while using `asyncio` behind
 the scenes! This means you're now able to do both of the following:
 
 .. code-block:: python
@@ -1238,7 +1238,7 @@ Bug fixes
 - "User joined" event was being treated as "User was invited".
 - SQLite's cursor should not be closed properly after usage.
 - ``await`` the updates task upon disconnection.
-- Some bug in Python 3.5.2's ``asyncio`` causing 100% CPU load if you
+- Some bug in Python 3.5.2's `asyncio` causing 100% CPU load if you
   forgot to call `client.disconnect()
   <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`.
   The method is called for you on object destruction, but you still should
@@ -1373,7 +1373,7 @@ Enhancements
 - ``pathlib.Path`` is now supported for downloading and uploading media.
 - Messages you send to yourself are now considered outgoing, unless they
   are forwarded.
-- The documentation has been updated with a brand new ``asyncio`` crash
+- The documentation has been updated with a brand new `asyncio` crash
   course to encourage you use it. You can still use the threaded version
   if you want though.
 - ``.name`` property is now properly supported when sending and downloading

readthedocs/misc/compatibility-and-convenience.rst

@@ -4,7 +4,7 @@
 Compatibility and Convenience
 =============================
 
-Telethon is an ``asyncio`` library. Compatibility is an important concern,
+Telethon is an `asyncio` library. Compatibility is an important concern,
 and while it can't always be kept and mistakes happens, the :ref:`changelog`
 is there to tell you when these important changes happen.
 
@@ -16,7 +16,7 @@ Compatibility
 
 Some decisions when developing will inevitable be proven wrong in the future.
 One of these decisions was using threads. Now that Python 3.4 is reaching EOL
-and using ``asyncio`` is usable as of Python 3.5 it makes sense for a library
+and using `asyncio` is usable as of Python 3.5 it makes sense for a library
 like Telethon to make a good use of it.
 
 If you have old code, **just use old versions** of the library! There is
@@ -34,7 +34,7 @@ and clean-ups. Using an older version is the right way to go.
 Sometimes, other small decisions are made. These all will be reflected in the
 :ref:`changelog` which you should read when upgrading.
 
-If you want to jump the ``asyncio`` boat, here are some of the things you will
+If you want to jump the `asyncio` boat, here are some of the things you will
 need to start migrating really old code:
 
 .. code-block:: python
@@ -91,7 +91,7 @@ Convenience
     This makes the examples shorter and easier to think about.
 
 For quick scripts that don't need updates, it's a lot more convenient to
-forget about ``asyncio`` and just work with sequential code. This can prove
+forget about `asyncio` and just work with sequential code. This can prove
 to be a powerful hybrid for running under the Python REPL too.
 
 .. code-block:: python
@@ -178,10 +178,10 @@ overhead you pay if you import it, and what you save if you don't.
 Learning
 ========
 
-You know the library uses ``asyncio`` everywhere, and you want to learn
-how to do things right. Even though ``asyncio`` is its own topic, the
+You know the library uses `asyncio` everywhere, and you want to learn
+how to do things right. Even though `asyncio` is its own topic, the
 documentation wants you to learn how to use Telethon correctly, and for
-that, you need to use ``asyncio`` correctly too. For this reason, there
+that, you need to use `asyncio` correctly too. For this reason, there
 is a section called :ref:`mastering-asyncio` that will introduce you to
-the ``asyncio`` world, with links to more resources for learning how to
+the `asyncio` world, with links to more resources for learning how to
 use it. Feel free to check that section out once you have read the rest.

readthedocs/quick-references/events-reference.rst

@@ -19,34 +19,79 @@ its **attributes** (the properties will be shown here).
 .. contents::
 
 
-CallbackQuery
+NewMessage
+==========
+
+Occurs whenever a new text message or a message with media arrives.
+
+.. note::
+
+    The new message event **should be treated as** a
+    normal `Message <telethon.tl.custom.message.Message>`, with
+    the following exceptions:
+
+    * ``pattern_match`` is the match object returned by ``pattern=``.
+    * ``message`` is **not** the message string. It's the `Message
+      <telethon.tl.custom.message.Message>` object.
+
+    Remember, this event is just a proxy over the message, so while
+    you won't see its attributes and properties, you can still access
+    them. Please see the full documentation for examples.
+
+Full documentation for the `NewMessage
+<telethon.events.newmessage.NewMessage>`.
+
+
+MessageEdited
 =============
 
-Full documentation for the `CallbackQuery
-<telethon.events.callbackquery.CallbackQuery>`.
+Occurs whenever a message is edited. Just like `NewMessage
+<telethon.events.newmessage.NewMessage>`, you should treat
+this event as a `Message <telethon.tl.custom.message.Message>`.
 
-.. currentmodule:: telethon.events.callbackquery.CallbackQuery.Event
+Full documentation for the `MessageEdited
+<telethon.events.messageedited.MessageEdited>`.
+
+
+MessageDeleted
+==============
+
+Occurs whenever a message is deleted. Note that this event isn't 100%
+reliable, since Telegram doesn't always notify the clients that a message
+was deleted.
+
+It only has the ``deleted_id`` and ``deleted_ids`` attributes
+(in addition to the chat if the deletion happened in a channel).
+
+Full documentation for the `MessageDeleted
+<telethon.events.messagedeleted.MessageDeleted>`.
+
+
+MessageRead
+===========
+
+Occurs whenever one or more messages are read in a chat.
+
+Full documentation for the `MessageRead
+<telethon.events.messageread.MessageRead>`.
+
+.. currentmodule:: telethon.events.messageread.MessageRead.Event
 
 .. autosummary::
     :nosignatures:
 
-        id
-        message_id
-        data
-        chat_instance
-        via_inline
+        inbox
+        message_ids
 
-        respond
-        reply
-        edit
-        delete
-        answer
-        get_message
+        get_messages
+        is_read
 
 
 ChatAction
 ==========
 
+Occurs whenever a user joins or leaves a chat, or a message is pinned.
+
 Full documentation for the `ChatAction
 <telethon.events.chataction.ChatAction>`.
 
@@ -76,9 +121,63 @@ Full documentation for the `ChatAction
         get_input_users
 
 
+UserUpdate
+==========
+
+Occurs whenever a user goes online, starts typing, etc.
+
+A lot of fields are attributes and not properties, so they
+are not shown here. Please refer to its full documentation.
+
+Full documentation for the `UserUpdate
+<telethon.events.userupdate.UserUpdate>`.
+
+.. currentmodule:: telethon.events.userupdate.UserUpdate.Event
+
+.. autosummary::
+    :nosignatures:
+
+        user
+        input_user
+        user_id
+
+        get_user
+        get_input_user
+
+
+CallbackQuery
+=============
+
+Occurs whenever you sign in as a bot and a user
+clicks one of the inline buttons on your messages.
+
+Full documentation for the `CallbackQuery
+<telethon.events.callbackquery.CallbackQuery>`.
+
+.. currentmodule:: telethon.events.callbackquery.CallbackQuery.Event
+
+.. autosummary::
+    :nosignatures:
+
+        id
+        message_id
+        data
+        chat_instance
+        via_inline
+
+        respond
+        reply
+        edit
+        delete
+        answer
+        get_message
+
 InlineQuery
 ===========
 
+Occurs whenever you sign in as a bot and a user
+sends an inline query such as ``@bot query``.
+
 Full documentation for the `InlineQuery
 <telethon.events.inlinequery.InlineQuery>`.
 
@@ -95,90 +194,9 @@ Full documentation for the `InlineQuery
 
         answer
 
-
-MessageDeleted
-==============
-
-Full documentation for the `MessageDeleted
-<telethon.events.messagedeleted.MessageDeleted>`.
-
-It only has the ``deleted_id`` and ``deleted_ids`` attributes
-(in addition to the chat if the deletion happened in a channel).
-
-
-MessageEdited
-=============
-
-Full documentation for the `MessageEdited
-<telethon.events.messageedited.MessageEdited>`.
-
-This event is the same as `NewMessage
-<telethon.events.newmessage.NewMessage>`,
-but occurs only when an edit happens.
-
-
-MessageRead
-===========
-
-Full documentation for the `MessageRead
-<telethon.events.messageread.MessageRead>`.
-
-.. currentmodule:: telethon.events.messageread.MessageRead.Event
-
-.. autosummary::
-    :nosignatures:
-
-        inbox
-        message_ids
-
-        get_messages
-        is_read
-
-
-NewMessage
-==========
-
-Full documentation for the `NewMessage
-<telethon.events.newmessage.NewMessage>`.
-
-Note that the new message event **should be treated as** a
-normal `Message <telethon.tl.custom.message.Message>`, with
-the following exceptions:
-
-* ``pattern_match`` is the match object returned by ``pattern=``.
-* ``message`` is **not** the message string. It's the `Message
-  <telethon.tl.custom.message.Message>` object.
-
-Remember, this event is just a proxy over the message, so while
-you won't see its attributes and properties, you can still access
-them.
-
-
 Raw
 ===
 
 Raw events are not actual events. Instead, they are the raw
 :tl:`Update` object that Telegram sends. You normally shouldn't
 need these.
-
-
-UserUpdate
-==========
-
-Full documentation for the `UserUpdate
-<telethon.events.userupdate.UserUpdate>`.
-
-A lot of fields are attributes and not properties, so they
-are not shown here.
-
-.. currentmodule:: telethon.events.userupdate.UserUpdate.Event
-
-.. autosummary::
-    :nosignatures:
-
-        user
-        input_user
-        user_id
-
-        get_user
-        get_input_user

readthedocs/quick-references/objects-reference.rst

@@ -249,7 +249,8 @@ InlineResult
 The `InlineResult <telethon.tl.custom.inlineresult.InlineResult>` object
 is returned inside a list by the `client.inline_query()
 <telethon.client.bots.BotMethods.inline_query>` method to make an inline
-query to a bot that supports being used in inline mode, such as ``@like``.
+query to a bot that supports being used in inline mode, such as
+`@like <https://t.me/like>`_.
 
 Note that the list returned is in fact a *subclass* of a list called
 `InlineResults <telethon.tl.custom.inlineresults.InlineResults>`, which,

telethon/client/auth.py

@@ -289,11 +289,12 @@ class AuthMethods(MessageParseMethods, UserMethods):
 
             password (`str`):
                 2FA password, should be used if a previous call raised
-                SessionPasswordNeededError.
+                ``SessionPasswordNeededError``.
 
             bot_token (`str`):
                 Used to sign in as a bot. Not all requests will be available.
-                This should be the hash the @BotFather gave you.
+                This should be the hash the `@BotFather <https://t.me/BotFather>`_
+                gave you.
 
             phone_code_hash (`str`, optional):
                 The hash returned by `send_code_request`. This can be left as

telethon/events/callbackquery.py

@@ -10,7 +10,8 @@ from ..tl.custom.sendergetter import SenderGetter
 @name_inner_event
 class CallbackQuery(EventBuilder):
     """
-    Represents a callback query event (when an inline button is clicked).
+    Occurs whenever you sign in as a bot and a user
+    clicks one of the inline buttons on your messages.
 
     Note that the `chats` parameter will **not** work with normal
     IDs or peers if the clicked inline button comes from a "via bot"

telethon/events/chataction.py

@@ -6,7 +6,7 @@ from ..tl import types, functions
 @name_inner_event
 class ChatAction(EventBuilder):
     """
-    Represents an action in a chat (such as user joined, left, or new pin).
+    Occurs whenever a user joins or leaves a chat, or a message is pinned.
     """
     @classmethod
     def build(cls, update):

telethon/events/inlinequery.py

@@ -12,7 +12,8 @@ from ..tl.custom.sendergetter import SenderGetter
 @name_inner_event
 class InlineQuery(EventBuilder):
     """
-    Represents an inline query event (when someone writes ``'@my_bot query'``).
+    Occurs whenever you sign in as a bot and a user
+    sends an inline query such as ``@bot query``.
 
     Args:
         users (`entity`, optional):

telethon/events/messagedeleted.py

@@ -5,7 +5,9 @@ from ..tl import types
 @name_inner_event
 class MessageDeleted(EventBuilder):
     """
-    Event fired when one or more messages are deleted.
+    Occurs whenever a message is deleted. Note that this event isn't 100%
+    reliable, since Telegram doesn't always notify the clients that a message
+    was deleted.
 
     .. important::
 

telethon/events/messageedited.py

@@ -6,7 +6,9 @@ from ..tl import types
 @name_inner_event
 class MessageEdited(NewMessage):
     """
-    Event fired when a message has been edited.
+    Occurs whenever a message is edited. Just like `NewMessage
+    <telethon.events.newmessage.NewMessage>`, you should treat
+    this event as a `Message <telethon.tl.custom.message.Message>`.
 
     .. warning::
 

telethon/events/messageread.py

@@ -6,7 +6,7 @@ from ..tl import types
 @name_inner_event
 class MessageRead(EventBuilder):
     """
-    Event fired when one or more messages have been read.
+    Occurs whenever one or more messages are read in a chat.
 
     Args:
         inbox (`bool`, optional):

telethon/events/newmessage.py

@@ -8,7 +8,7 @@ from ..tl import types
 @name_inner_event
 class NewMessage(EventBuilder):
     """
-    Represents a new message event builder.
+    Occurs whenever a new text message or a message with media arrives.
 
     Args:
         incoming (`bool`, optional):

telethon/events/raw.py

@@ -4,7 +4,9 @@ from .. import utils
 
 class Raw(EventBuilder):
     """
-    Represents a raw event. The event is the update itself.
+    Raw events are not actual events. Instead, they are the raw
+    :tl:`Update` object that Telegram sends. You normally shouldn't
+    need these.
 
     Args:
         types (`list` | `tuple` | `type`, optional):

telethon/events/userupdate.py

@@ -9,7 +9,7 @@ from ..tl.custom.sendergetter import SenderGetter
 @name_inner_event
 class UserUpdate(EventBuilder):
     """
-    Represents a user update (gone online, offline, joined Telegram).
+    Occurs whenever a user goes online, starts typing, etc.
     """
     @classmethod
     def build(cls, update):
@@ -32,7 +32,8 @@ class UserUpdate(EventBuilder):
 
     class Event(EventCommon, SenderGetter):
         """
-        Represents the event of a user status update (last seen, joined).
+        Represents the event of a user update
+        such as gone online, started typing, etc.
 
         Members:
             online (`bool`, optional):