Started the application userguide

docs/userguide/application.rst

@@ -0,0 +1,111 @@
+.. _guide-app:
+
+=============
+ Application
+=============
+
+The Celery library must instantiated before use, and this instance
+is called the application.
+
+Multiple Celery applications with different configuration
+and components can co-exist in the same process space,
+but there is always an app exposed as the 'current app' in each
+thread.
+
+Configuration
+=============
+
+There are lots of different options you can set that will change how
+Celery work.  These options can be set on the app instance directly,
+or you can use a dedicated configuration module.
+
+
+The current configuration is always available as :attr:`@Celery.conf`::
+
+    >>> celery.conf.CELERY_TIMEZONE
+    "Europe/London"
+
+The configuration actually consists of multiple dictionaries
+that are consulted in order:
+
+    #. Changes made at runtime.
+    #. Any configuration module (``loader.conf``).
+    #. The default configuration (:mod:`celery.app.defaults`).
+
+When the app is serialized
+only the configuration changes will be transferred.
+
+.. topic:: The "default app".
+
+    Celery did not always work this way, it used to be that
+    there was only a module-based API, and for backwards compatibility
+    the old API is still there.
+
+    Celery always creates a special app that is the "default app",
+    and this is used if no custom application has been instantiated.
+
+    The :mod:`celery.task` module is there to accommodate the old API,
+    and should not be used if you use a custom app. You should
+    always use the methods on the app instance, not the module based API.
+
+    For example, the old Task base class enables many compatibility
+    features where some may be incompatible with newer features, such
+    as task methods:
+
+    .. code-block:: python
+
+        from celery.task import Task   # << OLD Task base class.
+
+        from celery import Task        # << NEW base class.
+
+    The new base class is recommended even if you use the old
+    module-based API.
+
+
+
+.. topic:: Evolving the API
+
+    Celery has changed a lot in the 3 years since it was initially
+    created.
+
+    For example, in the beginning it was possible to use any callable as
+    a task::
+
+    .. code-block:: python
+
+        def hello(to):
+            return "hello %s" % to
+
+        >>> from celery.execute import apply_async
+
+        >>> apply_async(hello, ("world!", ))
+
+    or you could also create a ``Task`` class to set
+    certain options, or override other behavior
+
+    .. code-block:: python
+
+        from celery.task import Task
+        from celery.registry import tasks
+
+        class Hello(Task):
+            send_error_emails = True
+
+            def run(self, to):
+                return "hello %s" % to
+        tasks.register(Hello)
+
+        >>> Hello.delay("world!")
+
+    Later, it was decided that passing arbitrary call-ables
+    was an anti-pattern, since it makes it very hard to use
+    serializers other than pickle, and the feature was removed
+    in 2.0, replaced by task decorators::
+
+    .. code-block:: python
+
+        from celery.task import task
+
+        @task(send_error_emails=True)
+        def hello(x):
+            return "hello %s" % to

docs/userguide/index.rst

@@ -10,7 +10,7 @@
 .. toctree::
     :maxdepth: 2
 
-    overview
+    application
     tasks
     calling
     workers

docs/userguide/overview.rst

@@ -1,79 +0,0 @@
-.. _guide-overview:
-
-==========
- Overview
-==========
-
-.. contents::
-    :local:
-
-.. _overview-figure-1:
-
-.. figure:: ../images/celery-broker-worker-nodes.jpg
-
-    *Figure 1:* Worker and broker nodes.
-
-To use Celery you need at least two main components; a message broker and
-a worker.
-
-The message broker enables clients and workers to communicate through
-messaging.  There are several broker implementations available, the most
-popular being RabbitMQ.
-
-The worker processes messages, and consists of one or more physical (or virtual)
-nodes.
-
-
-Tasks
-=====
-
-The action to take whenever a message of a certain type is received is called
-a "task".
-
-* Go to :ref:`guide-tasks`.
-* Go to :ref:`guide-calling`.
-* Go to :ref:`guide-canvas`
-* Go to :ref:`guide-beat`.
-* Go to :ref:`guide-webhooks`.
-
-
-Workers
-=======
-Go to :ref:`guide-workers`.
-
-Monitoring
-==========
-Go to :ref:`guide-monitoring`.
-
-Routing
-=======
-
-.. _overview-figure-2:
-
-.. figure:: ../images/celery-worker-bindings.jpg
-
-    *Figure 2:* Worker bindings.
-
-Go to :ref:`guide-routing`.
-
-Celery takes advantage of AMQPs flexible routing model.  Tasks can be routed
-to specific servers, or a cluster of servers by binding workers to different
-queues. A single worker node can be bound to one or more queues.
-Multiple messaging scenarios are supported: round robin, point-to-point,
-broadcast (one-to-many), and more.
-
-Celery aims to hide the complexity of AMQP through features like
-:ref:`routing-automatic`, while still preserving the ability to go
-low level if that should be necessary.
-
-Ecosystem
-=========
-
-Kombu
------
-
-cyme
-----
-
-celerymon
----------

docs/whatsnew-2.6.rst

@@ -23,6 +23,21 @@ read the `django-celery changelog`_ and upgrade to `django-celery 2.6`_.
 This version is officially supported on CPython 2.5, 2.6, 2.7, 3.2 and 3.3,
 as well as PyPy and Jython.
 
+.. topic:: Highlights
+
+    - A new and improved API, that is both simpler and more powerful.
+
+        Everyone should read the new :ref:`first-steps` tutorial,
+        and the new :ref:`next-steps` tutorial.
+
+    - Documentation rewritten and updated to use the new API
+
+    - The worker is now thread-less, giving great performance improvements.
+
+    - This is the last version to support Python 2.5
+
+    - The new "Canvas" makes it easy to define complex workflows.
+
 
 .. _`website`: http://celeryproject.org/
 .. _`django-celery changelog`: http://bit.ly/djcelery-26-changelog