Clean up and complete RTD documentation

readthedocs/extra/basic/telegram-client.rst

@@ -0,0 +1,99 @@
+.. _telegram-client:
+
+==============
+TelegramClient
+==============
+
+
+Introduction
+************
+
+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
+to know what it offers.
+
+Since we're working with Python, one must not forget that we can do
+``help(client)`` or ``help(TelegramClient)`` at any time for a more
+detailed description and a list of all the available methods. Calling
+``help()`` from an interactive Python session will always list all the
+methods for any object, even yours!
+
+Interacting with the Telegram API is done through sending **requests**,
+this is, any "method" listed on the API. There are a few methods (and
+growing!) on the ``TelegramClient`` class that abstract you from the
+need of manually importing the requests you need.
+
+For instance, retrieving your own user can be done in a single line:
+
+    ``myself = client.get_me()``
+
+Internally, this method has sent a request to Telegram, who replied with
+the information about your own user, and then the desired information
+was extracted from their response.
+
+If you want to retrieve any other user, chat or channel (channels are a
+special subset of chats), you want to retrieve their "entity". This is
+how the library refers to either of these:
+
+    .. code-block:: python
+
+        # The method will infer that you've passed an username
+        # It also accepts phone numbers, and will get the user
+        # from your contact list.
+        lonami = client.get_entity('lonami')
+
+The so called "entities" are another important whole concept on its own,
+and you should
+Note that saving and using these entities will be more important when
+Accessing the Full API. For now, this is a good way to get information
+about an user or chat.
+
+Other common methods for quick scripts are also available:
+
+    .. code-block:: python
+
+        # Sending a message (use an entity/username/etc)
+        client.send_message('TheAyyBot', 'ayy')
+
+        # Sending a photo, or a file
+        client.send_file(myself, '/path/to/the/file.jpg', force_document=True)
+
+        # Downloading someone's profile photo. File is saved to 'where'
+        where = client.download_profile_photo(someone)
+
+        # Retrieving the message history
+        messages = client.get_message_history(someone)
+
+        # Downloading the media from a specific message
+        # You can specify either a directory, a filename, or nothing at all
+        where = client.download_media(message, '/path/to/output')
+
+        # Call .disconnect() when you're done
+        client.disconnect()
+
+Remember that you can call ``.stringify()`` to any object Telegram returns
+to pretty print it. Calling ``str(result)`` does the same operation, but on
+a single line.
+
+
+Available methods
+*****************
+
+This page lists all the "handy" methods available for you to use in the
+``TelegramClient`` class. These are simply wrappers around the "raw"
+Telegram API, making it much more manageable and easier to work with.
+
+Please refer to :ref:`accessing-the-full-api` if these aren't enough,
+and don't be afraid to read the source code of the InteractiveTelegramClient_
+or even the TelegramClient_ itself to learn how it works.
+
+
+.. _InteractiveTelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py
+.. _TelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon/telegram_client.py
+
+
+
+.. automodule:: telethon.telegram_client
+    :members:
+    :undoc-members:
+    :show-inheritance: