docs: move all instructions on Celery to Setup

Instead of having some info on Celery in both Installation and Setup, move
everything to Setup and do some rewrite.

Additionally, update some outdated URLs and remove unused link targets.

docs/installation.rst

@@ -4,7 +4,7 b''
 Installation on Unix/Linux
 ==========================
 
-**Kallithea** is written entirely in Python and requires Python version
+**Kallithea** is written entirely in Python_ and requires Python version
 2.6 or higher. Python 3.x is currently not supported.
 
 There are several ways to install Kallithea:
@@ -113,44 +113,6 b' To install as a regular user in ``~/.loc'
 
 You can now proceed to :ref:`setup`.
 
-Celery (optional)
------------------
-
-In order to gain maximum performance
-there are some third-party you must install. When Kallithea is used
-together with celery you have to install some kind of message broker,
-recommended one is rabbitmq_ to make the async tasks work.
-
-Of course Kallithea works in sync mode also and then you do not have to install
-any third party applications. However, using Celery_ will give you a large
-speed improvement when using many big repositories. If you plan to use
-Kallithea for say 7 to 10 repositories, Kallithea will perform perfectly well
-without celery running.
-
-If you make the decision to run Kallithea with celery make sure you run
-celeryd using paster and message broker together with the application.
-
-.. note::
-   Installing message broker and using celery is optional, Kallithea will
-   work perfectly fine without them.
-
-
-**Message Broker**
-
-- preferred is `RabbitMq <http://www.rabbitmq.com/>`_
-- A possible alternative is `Redis <http://code.google.com/p/redis/>`_
-
-For installation instructions you can visit:
-http://ask.github.com/celery/getting-started/index.html.
-This is a very nice tutorial on how to start using celery_ with rabbitmq_
-
-
-Next
-----
-
-You can now proceed to :ref:`setup`.
-
-
 Upgrading Kallithea from Python Package Index (PyPI)
 -----------------------------------------------------
 
@@ -245,7 +207,4 b' Or::'
 
 
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
-.. _python: http://www.python.org/
-.. _mercurial: http://mercurial.selenic.com/
-.. _celery: http://celeryproject.org/
-.. _rabbitmq: http://www.rabbitmq.com/
+.. _Python: http://www.python.org/

docs/setup.rst

@@ -15,7 +15,7 b' following command to do this::'
 
 - This will create the file `my.ini` in the current directory. This
   configuration file contains the various settings for Kallithea, e.g proxy
-  port, email settings, usage of static files, cache, celery settings and
+  port, email settings, usage of static files, cache, Celery settings and
   logging.
 
 
@@ -496,15 +496,30 b' when there are encode/decode errors.'
 Celery configuration
 --------------------
 
-Celery is configured in the Kallithea ini configuration files.
-Simply set use_celery=true in the ini file then add / change the configuration
-variables inside the ini file.
+Kallithea can use the distributed task queue system Celery_ to run tasks like
+cloning repositories or sending mails.
+
+Kallithea will in most setups work perfectly fine out of the box (without
+Celery), executing all tasks in the web server process. Some tasks can however
+take some time to run and it can be better to run such tasks asynchronously in
+a separate process so the web server can focus on serving web requests.
+
+For installation and configuration of Celery, see the `Celery documentation`_.
+Note that Celery requires a message broker service like RabbitMQ_ (recommended)
+or Redis_.
 
-Remember that the ini files use the format with '.' not with '_' like celery.
-So for example setting `BROKER_HOST` in celery means setting `broker.host` in
-the config file.
+The use of Celery is configured in the Kallithea ini configuration file.
+To enable it, simply set::
+
+ use_celery = true
 
-In order to start using celery run::
+and add or change the celery.* and broker.* configuration variables.
+
+Remember that the ini files use the format with '.' and not with '_' like
+Celery. So for example setting `BROKER_HOST` in Celery means setting
+`broker.host` in the configuration file.
+
+To start the Celery process, run::
 
  paster celeryd <configfile.ini>
 
@@ -757,8 +772,10 b' Some example init.d scripts can be found'
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 .. _python: http://www.python.org/
 .. _Mercurial: http://mercurial.selenic.com/
-.. _celery: http://celeryproject.org/
-.. _rabbitmq: http://www.rabbitmq.com/
+.. _Celery: http://celeryproject.org/
+.. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html
+.. _RabbitMQ: http://www.rabbitmq.com/
+.. _Redis: http://redis.io/
 .. _python-ldap: http://www.python-ldap.org/
 .. _mercurial-server: http://www.lshift.net/mercurial-server.html
 .. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories