Clean up and complete RTD documentation

readthedocs/extra/basic/working-with-updates.rst

@@ -14,23 +14,24 @@ The library can run in four distinguishable modes:
 - With several worker threads that run your update handlers.
 - A mix of the above.
 
-Since this section is about updates, we'll describe the simplest way to work with them.
-
-.. warning::
-    Remember that you should always call ``client.disconnect()`` once you're done.
+Since this section is about updates, we'll describe the simplest way to
+work with them.
 
 
 Using multiple workers
-^^^^^^^^^^^^^^^^^^^^^^^
+**********************
 
-When you create your client, simply pass a number to the ``update_workers`` parameter:
+When you create your client, simply pass a number to the
+``update_workers`` parameter:
 
     ``client = TelegramClient('session', api_id, api_hash, update_workers=4)``
 
-4 workers should suffice for most cases (this is also the default on `Python Telegram Bot`__).
-You can set this value to more, or even less if you need.
+4 workers should suffice for most cases (this is also the default on
+`Python Telegram Bot`__). You can set this value to more, or even less
+if you need.
 
-The next thing you want to do is to add a method that will be called when an `Update`__ arrives:
+The next thing you want to do is to add a method that will be called when
+an `Update`__ arrives:
 
     .. code-block:: python
 
@@ -41,7 +42,8 @@ The next thing you want to do is to add a method that will be called when an `Up
         # do more work here, or simply sleep!
 
 That's it! Now let's do something more interesting.
-Every time an user talks to use, let's reply to them with the same text reversed:
+Every time an user talks to use, let's reply to them with the same
+text reversed:
 
     .. code-block:: python
 
@@ -56,16 +58,18 @@ Every time an user talks to use, let's reply to them with the same text reversed
         input('Press enter to stop this!')
         client.disconnect()
 
-We only ask you one thing: don't keep this running for too long, or your contacts will go mad.
+We only ask you one thing: don't keep this running for too long, or your
+contacts will go mad.
 
 
 Spawning no worker at all
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+*************************
 
-All the workers do is loop forever and poll updates from a queue that is filled from the ``ReadThread``,
-responsible for reading every item off the network.
-If you only need a worker and the ``MainThread`` would be doing no other job,
-this is the preferred way. You can easily do the same as the workers like so:
+All the workers do is loop forever and poll updates from a queue that is
+filled from the ``ReadThread``, responsible for reading every item off
+the network. If you only need a worker and the ``MainThread`` would be
+doing no other job, this is the preferred way. You can easily do the same
+as the workers like so:
 
     .. code-block:: python
 
@@ -81,24 +85,27 @@ this is the preferred way. You can easily do the same as the workers like so:
 
         client.disconnect()
 
-Note that ``poll`` accepts a ``timeout=`` parameter,
-and it will return ``None`` if other thread got the update before you could or if the timeout expired,
-so it's important to check ``if not update``.
+Note that ``poll`` accepts a ``timeout=`` parameter, and it will return
+``None`` if other thread got the update before you could or if the timeout
+expired, so it's important to check ``if not update``.
 
-This can coexist with the rest of ``N`` workers, or you can set it to ``0`` additional workers:
+This can coexist with the rest of ``N`` workers, or you can set it to ``0``
+additional workers:
 
     ``client = TelegramClient('session', api_id, api_hash, update_workers=0)``
 
-You **must** set it to ``0`` (or other number), as it defaults to ``None`` and there is a different.
-``None`` workers means updates won't be processed *at all*,
-so you must set it to some value (0 or greater) if you want ``client.updates.poll()`` to work.
+You **must** set it to ``0`` (or other number), as it defaults to ``None``
+and there is a different. ``None`` workers means updates won't be processed
+*at all*, so you must set it to some value (``0`` or greater) if you want
+``client.updates.poll()`` to work.
 
 
 Using the main thread instead the ``ReadThread``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+************************************************
 
-If you have no work to do on the ``MainThread`` and you were planning to have a ``while True: sleep(1)``,
-don't do that. Instead, don't spawn the secondary ``ReadThread`` at all like so:
+If you have no work to do on the ``MainThread`` and you were planning to have
+a ``while True: sleep(1)``, don't do that. Instead, don't spawn the secondary
+``ReadThread`` at all like so:
 
     .. code-block:: python
 
@@ -111,8 +118,8 @@ And then ``.idle()`` from the ``MainThread``:
 
     ``client.idle()``
 
-You can stop it with :kbd:`Control+C`,
-and you can configure the signals to be used in a similar fashion to `Python Telegram Bot`__.
+You can stop it with :kbd:`Control+C`, and you can configure the signals
+to be used in a similar fashion to `Python Telegram Bot`__.
 
 As a complete example:
 
@@ -132,4 +139,4 @@ As a complete example:
 
 __ https://python-telegram-bot.org/
 __ https://lonamiwebs.github.io/Telethon/types/update.html
-__ https://github.com/python-telegram-bot/python-telegram-bot/blob/4b3315db6feebafb94edcaa803df52bb49999ced/telegram/ext/updater.py#L460
+__ https://github.com/python-telegram-bot/python-telegram-bot/blob/4b3315db6feebafb94edcaa803df52bb49999ced/telegram/ext/updater.py#L460