Completely overhaul the documentation

readthedocs/developing/coding-style.rst

@@ -0,0 +1,22 @@
+============
+Coding Style
+============
+
+
+Basically, make it **readable**, while keeping the style similar to the
+code of whatever file you're working on.
+
+Also note that not everyone has 4K screens for their primary monitors,
+so please try to stick to the 80-columns limit. This makes it easy to
+``git diff`` changes from a terminal before committing changes. If the
+line has to be long, please don't exceed 120 characters.
+
+For the commit messages, please make them *explanatory*. Not only
+they're helpful to troubleshoot when certain issues could have been
+introduced, but they're also used to construct the change log once a new
+version is ready.
+
+If you don't know enough Python, I strongly recommend reading `Dive Into
+Python 3 <http://www.diveintopython3.net/>`__, available online for
+free. For instance, remember to do ``if x is None`` or
+``if x is not None`` instead ``if x == None``!

readthedocs/developing/philosophy.rst

@@ -0,0 +1,25 @@
+==========
+Philosophy
+==========
+
+
+The intention of the library is to have an existing MTProto library
+existing with hardly any dependencies (indeed, wherever Python is
+available, you can run this library).
+
+Being written in Python means that performance will be nowhere close to
+other implementations written in, for instance, Java, C++, Rust, or
+pretty much any other compiled language. However, the library turns out
+to actually be pretty decent for common operations such as sending
+messages, receiving updates, or other scripting. Uploading files may be
+notably slower, but if you would like to contribute, pull requests are
+appreciated!
+
+If ``libssl`` is available on your system, the library will make use of
+it to speed up some critical parts such as encrypting and decrypting the
+messages. Files will notably be sent and downloaded faster.
+
+The main focus is to keep everything clean and simple, for everyone to
+understand how working with MTProto and Telegram works. Don't be afraid
+to read the source, the code won't bite you! It may prove useful when
+using the library on your own use cases.

readthedocs/developing/project-structure.rst

@@ -0,0 +1,47 @@
+=================
+Project Structure
+=================
+
+
+Main interface
+==============
+
+The library itself is under the ``telethon/`` directory. The
+``__init__.py`` file there exposes the main ``TelegramClient``, a class
+that servers as a nice interface with the most commonly used methods on
+Telegram such as sending messages, retrieving the message history,
+handling updates, etc.
+
+The ``TelegramClient`` inherits from several mixing ``Method`` classes,
+since there are so many methods that having them in a single file would
+make maintenance painful (it was three thousand lines before this separation
+happened!). It's a "god object", but there is only a way to interact with
+Telegram really.
+
+The ``TelegramBaseClient`` is an ABC which will support all of these mixins
+so they can work together nicely. It doesn't even know how to invoke things
+because they need to be resolved with user information first (to work with
+input entities comfortably).
+
+The client makes use of the ``network/mtprotosender.py``. The
+``MTProtoSender`` is responsible for connecting, reconnecting,
+packing, unpacking, sending and receiving items from the network.
+Basically, the low-level communication with Telegram, and handling
+MTProto-related functions and types such as ``BadSalt``.
+
+The sender makes use of a ``Connection`` class which knows the format in
+which outgoing messages should be sent (how to encode their length and
+their body, if they're further encrypted).
+
+Auto-generated code
+===================
+
+The files under ``telethon_generator/`` are used to generate the code
+that gets placed under ``telethon/tl/``. The parsers take in files in
+a specific format (such as ``.tl`` for objects and ``.json`` for errors)
+and spit out the generated classes which represent, as Python classes,
+the request and types defined in the ``.tl`` file. It also constructs
+an index so that they can be imported easily.
+
+Custom documentation can also be generated to easily navigate through
+the vast amount of items offered by the API.

readthedocs/developing/telegram-api-in-other-languages.rst

@@ -0,0 +1,73 @@
+===============================
+Telegram API in Other Languages
+===============================
+
+
+Telethon was made for **Python**, and as far as I know, there is no
+*exact* port to other languages. However, there *are* other
+implementations made by awesome people (one needs to be awesome to
+understand the official Telegram documentation) on several languages
+(even more Python too), listed below:
+
+C
+*
+
+Possibly the most well-known unofficial open source implementation out
+there by `@vysheng <https://github.com/vysheng>`__,
+`tgl <https://github.com/vysheng/tgl>`__, and its console client
+`telegram-cli <https://github.com/vysheng/tg>`__. Latest development
+has been moved to `BitBucket <https://bitbucket.org/vysheng/tdcli>`__.
+
+C++
+===
+
+The newest (and official) library, written from scratch, is called
+`tdlib <https://github.com/tdlib/td>`__ and is what the Telegram X
+uses. You can find more information in the official documentation,
+published `here <https://core.telegram.org/tdlib/docs/>`__.
+
+JavaScript
+==========
+
+`@zerobias <https://github.com/zerobias>`__ is working on
+`telegram-mtproto <https://github.com/zerobias/telegram-mtproto>`__,
+a work-in-progress JavaScript library installable via
+`npm <https://www.npmjs.com/>`__.
+
+Kotlin
+======
+
+`Kotlogram <https://github.com/badoualy/kotlogram>`__ is a Telegram
+implementation written in Kotlin (one of the
+`official <https://blog.jetbrains.com/kotlin/2017/05/kotlin-on-android-now-official/>`__
+languages for
+`Android <https://developer.android.com/kotlin/index.html>`__) by
+`@badoualy <https://github.com/badoualy>`__, currently as a beta–
+yet working.
+
+PHP
+===
+
+A PHP implementation is also available thanks to
+`@danog <https://github.com/danog>`__ and his
+`MadelineProto <https://github.com/danog/MadelineProto>`__ project, with
+a very nice `online
+documentation <https://daniil.it/MadelineProto/API_docs/>`__ too.
+
+Python
+======
+
+A fairly new (as of the end of 2017) Telegram library written from the
+ground up in Python by
+`@delivrance <https://github.com/delivrance>`__ and his
+`Pyrogram <https://github.com/pyrogram/pyrogram>`__ library.
+There isn't really a reason to pick it over Telethon and it'd be kinda
+sad to see you go, but it would be nice to know what you miss from each
+other library in either one so both can improve.
+
+Rust
+====
+
+Yet another work-in-progress implementation, this time for Rust thanks
+to `@JuanPotato <https://github.com/JuanPotato>`__ under the fancy
+name of `Vail <https://github.com/JuanPotato/Vail>`__.

readthedocs/developing/test-servers.rst

@@ -0,0 +1,37 @@
+============
+Test Servers
+============
+
+
+To run Telethon on a test server, use the following code:
+
+.. code-block:: python
+
+    client = TelegramClient(None, api_id, api_hash)
+    client.session.set_dc(dc_id, '149.154.167.40', 80)
+
+You can check your ``'test ip'`` on https://my.telegram.org.
+
+You should set ``None`` session so to ensure you're generating a new
+authorization key for it (it would fail if you used a session where you
+had previously connected to another data center).
+
+Note that port 443 might not work, so you can try with 80 instead.
+
+Once you're connected, you'll likely be asked to either sign in or sign up.
+Remember `anyone can access the phone you
+choose <https://core.telegram.org/api/datacenter#testing-redirects>`__,
+so don't store sensitive data here.
+
+Valid phone numbers are ``99966XYYYY``, where ``X`` is the ``dc_id`` and
+``YYYY`` is any number you want, for example, ``1234`` in ``dc_id = 2`` would
+be ``9996621234``. The code sent by Telegram will be ``dc_id`` repeated five
+times, in this case, ``22222`` so we can hardcode that:
+
+.. code-block:: python
+
+    client = TelegramClient(None, api_id, api_hash)
+    client.session.set_dc(2, '149.154.167.40', 80)
+    client.start(
+        phone='9996621234', code_callback=lambda: '22222'
+    )

readthedocs/developing/tips-for-porting-the-project.rst

@@ -0,0 +1,17 @@
+============================
+Tips for Porting the Project
+============================
+
+
+If you're going to use the code on this repository to guide you, please
+be kind and don't forget to mention it helped you!
+
+You should start by reading the source code on the `first
+release <https://github.com/LonamiWebs/Telethon/releases/tag/v0.1>`__ of
+the project, and start creating a ``MTProtoSender``. Once this is made,
+you should write by hand the code to authenticate on the Telegram's
+server, which are some steps required to get the key required to talk to
+them. Save it somewhere! Then, simply mimic, or reinvent other parts of
+the code, and it will be ready to go within a few days.
+
+Good luck!

readthedocs/developing/understanding-the-type-language.rst

@@ -0,0 +1,33 @@
+===============================
+Understanding the Type Language
+===============================
+
+
+`Telegram's Type Language <https://core.telegram.org/mtproto/TL>`__
+(also known as TL, found on ``.tl`` files) is a concise way to define
+what other programming languages commonly call classes or structs.
+
+Every definition is written as follows for a Telegram object is defined
+as follows:
+
+    ``name#id argument_name:argument_type = CommonType``
+
+This means that in a single line you know what the ``TLObject`` name is.
+You know it's unique ID, and you know what arguments it has. It really
+isn't that hard to write a generator for generating code to any
+platform!
+
+The generated code should also be able to *encode* the ``TLObject`` (let
+this be a request or a type) into bytes, so they can be sent over the
+network. This isn't a big deal either, because you know how the
+``TLObject``\ 's are made, and how the types should be serialized.
+
+You can either write your own code generator, or use the one this
+library provides, but please be kind and keep some special mention to
+this project for helping you out.
+
+This is only a introduction. The ``TL`` language is not *that* easy. But
+it's not that hard either. You're free to sniff the
+``telethon_generator/`` files and learn how to parse other more complex
+lines, such as ``flags`` (to indicate things that may or may not be
+written at all) and ``vector``\ 's.