From 34f4730337f03e6750c8428dbe4e11c810d0dd7d Mon Sep 17 00:00:00 2001
From: Lonami Exo <totufals@hotmail.com>
Date: Sun, 15 Apr 2018 14:04:58 +0200
Subject: [PATCH] Add new examples to the docs and update project structure

---
 .../extra/developing/project-structure.rst    | 12 ++--
 readthedocs/extra/examples/users.rst          | 70 +++++++++++++++++++
 readthedocs/index.rst                         |  1 +
 3 files changed, 79 insertions(+), 4 deletions(-)
 create mode 100644 readthedocs/extra/examples/users.rst

diff --git a/readthedocs/extra/developing/project-structure.rst b/readthedocs/extra/developing/project-structure.rst
index d40c6031..c745d6d6 100644
--- a/readthedocs/extra/developing/project-structure.rst
+++ b/readthedocs/extra/developing/project-structure.rst
@@ -37,7 +37,11 @@ Auto-generated code
 *******************
 
 The files under ``telethon_generator/`` are used to generate the code
-that gets placed under ``telethon/tl/``. The ``TLGenerator`` takes in a
-``.tl`` file, and spits 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.
+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.
diff --git a/readthedocs/extra/examples/users.rst b/readthedocs/extra/examples/users.rst
new file mode 100644
index 00000000..351ce186
--- /dev/null
+++ b/readthedocs/extra/examples/users.rst
@@ -0,0 +1,70 @@
+=====
+Users
+=====
+
+
+.. note::
+
+    These examples assume you have read :ref:`accessing-the-full-api`.
+
+
+Retrieving full information
+***************************
+
+If you need to retrieve the bio, biography or about information for an user
+you should use :tl:`GetFullUser`:
+
+
+    .. code-block:: python
+
+        from telethon.tl.functions.users import GetFullUserRequest
+
+        full = client(GetFullUserRequest(user))
+        # or even
+        full = client(GetFullUserRequest('username'))
+
+        bio = full.about
+
+
+See :tl:`UserFull` to know what other fields you can access.
+
+
+Updating your name and/or bio
+*****************************
+
+The first name, last name and bio (about) can all be changed with the same
+request. Omitted fields won't change after invoking :tl:`UpdateProfile`:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.account import UpdateProfileRequest
+
+        client(UpdateProfileRequest(about='This is a test from Telethon'))
+
+
+Updating your username
+**********************
+
+You need to use :tl:`account.UpdateUsername`:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.account import UpdateUsernameRequest
+
+        client(UpdateUsernameRequest('new_username'))
+
+
+Updating your profile photo
+***************************
+
+The easiest way is to upload a new file and use that as the profile photo
+through :tl:`UploadProfilePhoto`:
+
+
+    .. code-block:: python
+
+        from telethon.tl.functions.photos import UploadProfilePhotoRequest
+
+        client(functions.photos.UploadProfilePhotoRequest(
+            client.upload_file('/path/to/some/file')
+        ))
diff --git a/readthedocs/index.rst b/readthedocs/index.rst
index 89d2c510..01301eaa 100644
--- a/readthedocs/index.rst
+++ b/readthedocs/index.rst
@@ -61,6 +61,7 @@ heavy job for you, so you can focus on developing an application.
 
    extra/examples/working-with-messages
    extra/examples/chats-and-channels
+   extra/examples/users
    extra/examples/bots
    extra/examples/projects-using-telethon