General documentation cleanup

Author: Pietro Albini

docs/api/bot.rst

@@ -3,9 +3,9 @@
 
 .. api-bot::
 
-~~~~~~~~~~~~~~~~~
+=================
 Bots creation API
-~~~~~~~~~~~~~~~~~
+=================
 
 botogram is a microframework aimed to help you creating bots. It's obvious it
 has something to create them! Here is the reference of all the needed

docs/api/channels.rst

@@ -3,9 +3,9 @@
 
 .. _api-channels:
 
-~~~~~~~~~~~~
+============
 Channels API
-~~~~~~~~~~~~
+============
 
 The Channels API provides a lightweight way to interact with channels. If you
 just want to send messages to a channel, it's better if you use this.

docs/api/components.rst

@@ -3,9 +3,9 @@
 
 .. _api-components:
 
-~~~~~~~~~~~~~~~~~~~~~~~
+=======================
 Components creation API
-~~~~~~~~~~~~~~~~~~~~~~~
+=======================
 
 Creating components is one of the most useful features of botogram, since they
 allows you to reuse parts of your code in multiple bots. You can learn more

docs/api/index.rst

@@ -3,9 +3,9 @@
 
 .. _api:
 
-~~~~~~~~~~~~~
+=============
 API reference
-~~~~~~~~~~~~~
+=============
 
 This section will cover the full reference of botogram's public API. The
 API will be kept backward compatible for at least the next release, even if

docs/api/telegram.rst

@@ -3,9 +3,9 @@
 
 .. _api-telegram:
 
-~~~~~~~~~~~~~~~~~~~~
+====================
 Telegram API wrapper
-~~~~~~~~~~~~~~~~~~~~
+====================
 
 As an advantage to using botogram's :ref:`higher level API<api-bot>` and bot
 runner, many distracting and tedious details of working with
@@ -16,9 +16,6 @@ integrated into the classes presented here. These classes wrap Telegram's
 `API types`_ and detail the core objects your bot will deal with when going
 about its business.
 
-Available Classes
-=================
-
 * :py:class:`~botogram.User`
 * :py:class:`~botogram.Chat`
 * :py:class:`~botogram.Message`

docs/api/utility.rst

@@ -3,9 +3,9 @@
 
 .. api-utility::
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+================================
 Utility functions and decorators
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+================================
 
 botogram ships with some functions and decorators aimed to simplify the bots
 development. Feel free to use them when you need them.

docs/changelog.rst

@@ -3,9 +3,9 @@
 
 .. _changelog:
 
-~~~~~~~~~~~~~~~~~~
+==================
 botogram changelog
-~~~~~~~~~~~~~~~~~~
+==================
 
 Here you can see what changed in every botogram release.
 

docs/channels.rst

@@ -3,9 +3,9 @@
 
 .. _channels:
 
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 Working with channels
-~~~~~~~~~~~~~~~~~~~~~
+=====================
 
 Telegram Channels provides a way to broadcast a message to multiple users. You
 can manually send messages to them with your preferred Telegram client, but
@@ -15,7 +15,6 @@ With botogram you can easily do that, without even the need to run the bot.
 
 .. _channels-preparation:
 
-===========
 Preparation
 ===========
 
@@ -33,7 +32,6 @@ channel. From it you should add your bot, and then you're ready.
 
 .. _channels-standalone:
 
-=========================
 Manage without a full bot
 =========================
 
@@ -61,7 +59,6 @@ For example, if you want to send a text message you should do:
 
 .. _channels-bot:
 
-=========================
 Manage from a running bot
 =========================
 
@@ -88,4 +85,5 @@ cites botogram in a chat, you can do this:
            user = message.from_.username
 
        bot.send("@my_channel", "%s mentioned botogram!" % user)
-.. _@botfather: https://telegram.me/botfather
+
+.. _@botfather: https://telegram.me/botfather

docs/custom-components.rst

@@ -3,9 +3,9 @@
 
 .. _custom-components:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
 Creating custom components
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
 
 Hopefully you'll get to a point when you've made a few bots. The problem is,
 there's a high chance parts of the code are duplicated between the bots. For
@@ -19,7 +19,6 @@ bot.
 
 .. _custom-components-conduct:
 
-==========================
 Components code of conduct
 ==========================
 
@@ -52,7 +51,6 @@ simplifying the end-user experience:
 
 .. _custom-components-example:
 
-====================
 An example component
 ====================
 
@@ -124,7 +122,6 @@ source code of the component is the following:
 
 .. _custom-components-use:
 
-========================
 Using a custom component
 ========================
 

docs/deploy/common.rst

@@ -1,14 +1,18 @@
 .. Copyright (c) 2015 Pietro Albini <[email protected]>
    Released under the MIT license.
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _deploy-common:
+
+=============================
 Common deployment information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================
 
 Even if different deployment techniques are *really* different, all of them
 have two essential things in common: server security and application
 configuration.
 
+.. _deploy-common-security:
+
 Server security considerations
 ==============================
 
@@ -37,6 +41,8 @@ others' things.
   communicate to ``api.telegram.org`` with HTTPS. You can block everything else
   your bot doesn't use.
 
+.. _deploy-common-multiple:
+
 Running multiple bots in the same process
 =========================================