Docs improvements

docs/getting-started/introduction.rst

@@ -50,7 +50,7 @@ What do I need?
 
 *Celery* requires a message broker to send and receive messages.
 The RabbitMQ, Redis and MongoDB broker transports are feature complete,
-but there is also support for a myriad of other solutions, including
+but there's also support for a myriad of other solutions, including
 using SQLite for local development.
 
 *Celery* can run on a single machine, on multiple machines, or even
@@ -69,7 +69,7 @@ getting started tutorials:
 Celery is…
 ==========
 
-.. topic:: ”
+.. topic:: \ 
 
     - **Simple**
 
@@ -142,7 +142,6 @@ Celery is…
             - *zlib*, *bzip2* compression.
             - Cryptographic message signing.
 
-
 Features
 ========
 
@@ -313,3 +312,5 @@ Quickjump
         - :ref:`Signals <signals>`
         - :ref:`FAQ <faq>`
         - :ref:`API Reference <apiref>`
+
+.. include:: ../includes/installation.txt

docs/getting-started/next-steps.rst

@@ -366,11 +366,49 @@ The Primitives
 The primitives are also subtasks themselves, so that they can be combined
 in any number of ways to compose complex workflows.
 
-Here's some examples::
-
 Be sure to read more about workflows in the :ref:`Canvas <guide-canvas>` user
 guide.
 
 
+Routing
+=======
+
+Celery supports all of the routing facilities provided by AMQP,
+but it also supports simple routing where messages are sent to named queues.
+
+The :setting:`CELERY_ROUTES` setting enables you to route tasks by name
+and keep everything centralized in one location::
+
+    celery.conf.update(
+        CELERY_ROUTES = {
+            'proj.tasks.add': {'queue': 'hipri'},
+        },
+    )
+
+You can also specify the queue at runtime
+with the ``queue`` argument to ``apply_async``::
+
+    >>> from proj.tasks import add
+    >>> add.apply_async((2, 2), queue='hipri')
+
+You can then make a worker consume from this queue by
+specifying the :option:`-Q` option::
+
+    $ celery -A proj worker -Q hipri
+
+You may specify multiple queues by using a comma separated list,
+for example you can make the worker consume from both the default
+queue, and the ``hipri`` queue, where
+the default queue is named ``celery`` for historical reasons::
+
+    $ celery -A proj worker -Q hipri,celery
+
+The order of the queues doesn't matter as the worker will
+give equal weight to the queues.
+
+To learn more about routing, including taking use of the full
+power of AMQP routing, see the :ref:`Routing Guide <guide-routing>`.
+
+
 
 **This document is incomplete - and ends here :(**

docs/includes/installation.txt

@@ -1,18 +1,56 @@
+.. _celery-installation:
+
+Installation
+============
+
 You can install Celery either via the Python Package Index (PyPI)
 or from source.
 
 To install using `pip`,::
 
-    $ pip install Celery
+    $ pip install -U Celery
 
 To install using `easy_install`,::
 
-    $ easy_install Celery
+    $ easy_install -U Celery
+
+.. _bundles:
+
+Bundles
+-------
+
+Celery also defines a group of bundles that can be used
+to install Celery and the dependencies for a given feature.
+
+The following bundles are available:
+
+:`celery-with-redis`_:
+    for using Redis as a broker.
+
+:`celery-with-mongodb`_:
+    for using MongoDB as a broker.
+
+:`django-celery-with-redis`_:
+    for Django, and using Redis as a broker.
+
+:`django-celery-with-mongodb`_:
+    for Django, and using MongoDB as a broker.
+
+.. _`celery-with-redis`:
+    http://pypi.python.org/pypi/celery-with-redis/
+.. _`celery-with-mongodb`:
+    http://pypi.python.org/pypi/celery-with-mongdb/
+.. _`django-celery-with-redis`:
+    http://pypi.python.org/pypi/django-celery-with-redis/
+.. _`django-celery-with-mongodb`:
+    http://pypi.python.org/pypi/django-celery-with-mongdb/
+
+.. _celery-installing-from-source:
 
 Downloading and installing from source
 --------------------------------------
 
-Download the latest version of `celery` from
+Download the latest version of Celery from
 http://pypi.python.org/pypi/celery/
 
 You can install it by doing the following,::
@@ -20,11 +58,28 @@ You can install it by doing the following,::
     $ tar xvfz celery-0.0.0.tar.gz
     $ cd celery-0.0.0
     $ python setup.py build
-    # python setup.py install # as root
+    # python setup.py install
+
+The last command must be executed as a privileged user if
+you are not currently using a virtualenv.
+
+.. _celery-installing-from-git:
 
 Using the development version
-------------------------------
+-----------------------------
 
 You can clone the repository by doing the following::
 
     $ git clone https://github.com/celery/celery
+    $ cd celery
+    $ python setup.py develop
+
+The development version will usually also depend on the development
+version of `kombu`_, the messaging framework Celery uses
+to send and receive messages, so you should also install that from git::
+
+    $ git clone https://github.com/celery/kombu
+    $ cd kombu
+    $ python setup.py develop
+
+.. _`kombu`: http://kombu.readthedocs.org/en/latest/

docs/includes/introduction.txt

@@ -104,24 +104,29 @@ and the progress of the task can be tracked (called the task's *state*).
 Example
 =======
 
-You probably want to see some code by now, so here's an example task
-which adds two numbers:
+You probably want to see some code by now, this is the simplest
+Celery application you can make, you can put it in a module
+named ``tasks.py``:
 
 .. code-block:: python
 
-    from celery import task
+    from celery import Celery
 
-    @task()
+    celery = Celery(broker='amqp://guest@localhost://')
+
+    @celery.task()
     def add(x, y):
         return x + y
 
 You can execute the task in the background, or wait for it to finish::
 
     >>> result = add.delay(4, 4)
-    >>> result.wait() # wait for and return the result
+    >>> result.get(timeout=1)  # wait for and return the result
     8
 
-Simple!
+But before the task can execute you need to start a worker::
+
+    $ celery --app=tasks worker -l info
 
 .. _celery-features:
 
@@ -227,89 +232,6 @@ Documentation
 =============
 
 The `latest documentation`_ with user guides, tutorials and API reference
-is hosted at Github.
-
-.. _`latest documentation`: http://celery.github.com/celery/
-
-.. _celery-installation:
-
-Installation
-============
-
-You can install Celery either via the Python Package Index (PyPI)
-or from source.
-
-To install using `pip`,::
-
-    $ pip install -U Celery
-
-To install using `easy_install`,::
-
-    $ easy_install -U Celery
-
-.. _bundles:
-
-Bundles
--------
-
-Celery also defines a group of bundles that can be used
-to install Celery and the dependencies for a given feature.
-
-The following bundles are available:
-
-:`celery-with-redis`_:
-    for using Redis as a broker.
-
-:`celery-with-mongodb`_:
-    for using MongoDB as a broker.
-
-:`django-celery-with-redis`_:
-    for Django, and using Redis as a broker.
-
-:`django-celery-with-mongodb`_:
-    for Django, and using MongoDB as a broker.
-
-.. _`celery-with-redis`:
-    http://pypi.python.org/pypi/celery-with-redis/
-.. _`celery-with-mongodb`:
-    http://pypi.python.org/pypi/celery-with-mongdb/
-.. _`django-celery-with-redis`:
-    http://pypi.python.org/pypi/django-celery-with-redis/
-.. _`django-celery-with-mongodb`:
-    http://pypi.python.org/pypi/django-celery-with-mongdb/
-
-.. _celery-installing-from-source:
-
-Downloading and installing from source
---------------------------------------
-
-Download the latest version of Celery from
-http://pypi.python.org/pypi/celery/
-
-You can install it by doing the following,::
-
-    $ tar xvfz celery-0.0.0.tar.gz
-    $ cd celery-0.0.0
-    $ python setup.py build
-    # python setup.py install # as root
-
-.. _celery-installing-from-git:
-
-Using the development version
------------------------------
-
-You can clone the repository by doing the following::
-
-    $ git clone https://github.com/celery/celery
-    $ cd celery
-    $ python setup.py develop
-
-The development version will usually also depend on the development
-version of `kombu`_, the messaging framework Celery uses
-to send and receive messages, so you should also install that from git::
-
-    $ git clone https://github.com/celery/kombu
-    $ cd kombu
-    $ python setup.py develop
+is hosted at Read The Docs.
 
-.. _`kombu`: http://kombu.readthedocs.org/en/latest/
+.. _`latest documentation`: http://docs.celeryproject.org/en/latest/

docs/templates/readme.txt

@@ -6,4 +6,6 @@
 
 .. include:: ../includes/introduction.txt
 
+.. include:: ../includes/installation.txt
+
 .. include:: ../includes/resources.txt