Add narrative documentation about a bot's structure

Author: Pietro Albini

docs/bot-structure.rst

@@ -0,0 +1,98 @@
+.. Copyright (c) 2016 Pietro Albini <[email protected]>
+   Released under the MIT license
+
+.. _bot-structure:
+
+===========================
+Structure of a botogram bot
+===========================
+
+.. TODO - Rewrite this
+
+As a framework, botogram requires you to code your bot in a specific way. This
+means, you must follow a simple structure, explained here.
+
+.. _bot-structure-skeleton:
+
+A bot's skeleton
+================
+
+Even if you write two completly different bots, you'll have the same
+boilerplate code in both of them. This is because you need to create the bot
+instance, and start the runner after you executed all of your bot's code.
+
+botogram tries to reduce the boilerplate code as much as possible, but some of
+it is needed anyway. Here there is all the required code:
+
+.. code-block:: python
+
+   import botogram
+   bot = botogram.create("YOUR-API-KEY")
+
+   # Your code goes here
+
+   if __name__ == "__main__":
+       bot.run()
+
+As you can see, there are two required code blocks in botogram:
+
+* The first one imports botogram in your program, and creates a bot instance
+  you can start to customize.
+
+* The second one executes the bot. The if clausole is needed only if you plan
+  to run your bot on Windows, so if you're using Linux or OSX you can omit it.
+
+So, that's all the code required to create a bot with botogram. You can now
+start the actual bot creation!
+
+.. _bot-structure-hooks:
+
+Introduction to hooks
+=====================
+
+Hooks are the way to go to add some logic to your bot: they allows you to react
+when an user calls a command, write something or a lot more situations. Hooks
+are added to your bot with decorated functions, or :ref:`with components
+<custom-components>`.
+
+For example, this is an hook which is executed when someone calls the ``/test``
+command:
+
+.. code-block:: python
+
+   @bot.command("test")
+   def test_command(chat, message, args):
+       # Your hook's code
+
+You can put any code you want in each hook, but remember hooks might be
+executed in different processes by the runner, so avoid using global variables.
+If you need to store global state check out :ref:`shared memory
+<shared-memory>`.
+
+.. _bot-structure-hooks-args:
+
+Dynamic hooks arguments
+=======================
+
+Hooks are usually called with a lot of useful information, but you don't need
+all of it every time. For example, you might not need shared memory in a whole
+bot, but you have to use it everytime in another.
+
+In order to avoid having to write everytime a really long list of arguments,
+botogram is smart enought to figure out what you need and provide only that.
+So, if in a command you just need the message and the shared memory, you can
+define your hook this way:
+
+.. code-block:: python
+
+   @bot.command("test")
+   def test_command(message, shared):
+       # Your hook's code
+
+In addition to the arguments provided by each hook, botogram allows you to
+request those additional arguments:
+
+* **bot**, which is an instance of the current bot.
+
+* **shared**, which is an instance of your bot/component's :ref:`shared memory
+  <shared-memory>`.

docs/index.rst

@@ -53,6 +53,7 @@ Narrative documentation
    :maxdepth: 2
 
    bot-creation
+   bot-structure
    shared-memory
    tasks
    custom-components

docs/tricks.rst

@@ -11,39 +11,6 @@ The whole point of botogram is to make your life easier when creating Telegram
 bots. In order to do so in a better way, there are some tricks you can use to
 speed the development up.
 
-.. _tricks-dynamic-arguments:
-
-Dynamic arguments
-=================
-
-There are a lot of information and methods you can get from every decorator,
-but you don't always need them. botogram is smart enough to know which
-arguments you want and in which order you want them. This means you can request
-only the ones you need:
-
-.. code-block:: python
-
-   @botogram.command("test")
-   def test(args, chat):
-       chat.send(" ".join(args))
-
-By default, the :py:meth:`~botogram.Bot.command` decorator provides three
-arguments: ``chat``, ``message`` and ``args``. Instead, the function above
-requested only two of them, and botogram is able to provide only them in the
-right order.
-
-Please remember this will work only if a function is called directly by
-botogram (for example when a command is issued by a user). If you call it by
-hand, you'll need to provide the arguments by hand.
-
-There are some extra arguments you can request from every function called by
-botogram, without being directly provided by the decorator:
-
-* **bot**, which is an instance of the current bot.
-
-* **shared**, which is an instance of the bot's
-  :ref:`shared memory <shared-memory>`.
-
 .. _tricks-messages-syntax:
 
 Rich formatting with message syntaxes