Add documentation

client/doc/developing/changelog.rst

@@ -0,0 +1,8 @@
+Changelog (Version History)
+===========================
+
+
+v2 alpha
+--------
+
+WIP!

client/doc/developing/coding-style.rst

@@ -0,0 +1,17 @@
+Coding style
+============
+
+Knowledge of Python is a obviously a must to develop a Python library.
+A good online resource is `Dive Into Python 3 <http://www.diveintopython3.net/>`_.
+
+Telethon uses multiple tools to automatically format the code and check for linting rules.
+This means you can simply ignore formatting and let the tools handle it for you.
+You can find these tools under the ``tools/`` folder.
+
+The documentation is written with mostly a newline after every period.
+This is not a hard rule.
+Lines can be cut earlier if they become too long to be comfortable.
+
+Commit messages should be short and descriptive.
+They should start with an action in the present ("Fix" and not "Fixed").
+This saves a few characters and represents what the commit will "do" after applied.

client/doc/developing/migration-guide.rst

@@ -0,0 +1,4 @@
+Migrating from v1 to v2
+=======================
+
+WIP!

client/doc/developing/philosophy.rst

@@ -0,0 +1,10 @@
+Philosophy
+==========
+
+* Dependencies should only be added when absolutely necessary.
+* Dependencies written in anything other than Python cannot be mandatory.
+* The library must work correctly with no system dependencies other than Python 3.
+* Strict type-checking is required to pass everywhere in the library to make upgrades easier.
+* The code structure must make use of hard and clear boundaries to keep the different parts decoupled.
+* The API should cover only the most commonly used features to avoid bloat and reduce maintenance costs.
+* Documentation must be a pleasure to use and contain plenty of code examples.

client/doc/developing/project-structure.rst

@@ -0,0 +1,95 @@
+Project Structure
+=================
+
+.. currentmodule:: telethon
+
+The repository contains several folders, each with their own "package".
+
+
+benches/
+--------
+
+This folder contains different benchmarks.
+Pretty straightforward.
+
+
+stubs/
+------
+
+If a dependency doesn't support typing, files here must work around that.
+
+
+tools/
+------
+
+Various utility scripts.
+Each script should have a "comment" at the top explaining what they are for.
+
+See ``DEVELOPING.md`` in the repository root to learn how to use some of the tools.
+
+
+generator/
+----------
+
+A package that should not be published and is only used when developing the library.
+The implementation is private and exists under the ``src/*/_impl/`` folder.
+Only select parts are exported under public modules.
+Tests live under ``tests/``.
+
+The implementation consists of a parser and a code generator.
+
+The parser is able to read parse ``.tl`` files (Type-Language definition files).
+It doesn't do anything with the files other than to represent the content as Python objects.
+
+The code generator uses the parsed definitions to generate Python code.
+Most of the code to serialize and deserialize objects lives under ``serde/``.
+
+An in-memory "filesystem" structure is kept before writing all files to disk.
+This makes it possible to execute most of the process in a sans-io manner.
+Once the code generation finishes, all files are written to disk at once.
+
+See ``DEVELOPING.md`` in the repository root to learn how to generate code.
+
+
+client/
+-------
+
+The Telethon client library and documentation lives here.
+This is the package that gets published.
+The implementation is private and exists under the ``src/*/_impl/`` folder.
+Only select parts are exported under public modules.
+Tests live under ``tests/``.
+
+The client implementation consists of several subpackages.
+
+The ``tl`` package sits at the bottom.
+It is where the generated code is placed.
+It also contains some of the definitions needed for the generated code to work.
+Even though all the :term:`RPC` live here, this package can't do anything by itself.
+
+The ``crypto`` package implements all the encryption and decryption rules used by Telegram.
+Details concerning the :term:`MTProto` are mostly avoided, so the package can be generally useful.
+
+The ``mtproto`` package implements the logic required to talk to Telegram.
+It is implemented in a sans-io manner.
+This package is responsible for generating an authorization key and serializing packets.
+It also contains some optimizations which are not strictly necessary when implementing the library.
+
+The ``mtsender`` package simply adds IO to ``mtproto``.
+It is responsible for driving the network, enqueuing requests, and waiting for results.
+
+The ``session`` crate implements what's needed to manage the :term:`session` state.
+The logic to handle and correctly order updates also lives here, in a sans-io manner.
+
+The ``client`` ties everything together.
+This is what defines the Pythonic API to interact with Telegram.
+Custom object and event types also live here.
+
+Even though only common methods are implemented, the code is still huge.
+For this reason, the :class:`Client` implementation is separated from the class definition.
+The class definition only contains documentation and calls functions defined in other files.
+A tool under ``tools/`` exists to make it easy to keep these two in sync.
+
+If you plan to port the library to a different language, good luck!
+You will need a code generator, the ``crypto``, ``mtproto`` and ``mtsender`` packages to have an initial working version.
+The tests are your friend, write them too!