diff --git a/README.rst b/README.rst
index 491e280..ccb0483 100644
--- a/README.rst
+++ b/README.rst
@@ -41,9 +41,11 @@
:target: https://github.com/inveniosoftware/invenio-celery/blob/master/LICENSE
-Celery module for Invenio.
+Celery distributed task queue module for Invenio.
-*This is an experimental developer preview release.*
+Invenio-Celery is a small discovery layer that takes care of discovering and
+loading tasks from other Invenio modules, as well as providing configuration
+defaults for Celery usage in Invenio. Invenio-Celery relies on Flask-CeleryExt
+for integrating Flask and Celery with application factories.
-* Free software: GPLv2 license
-* Documentation: https://invenio-celery.readthedocs.io/
+Further documentation available at https://invenio-celery.readthedocs.io/
diff --git a/docs/conf.py b/docs/conf.py
index 548acc4..bf88226 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -132,7 +132,7 @@
html_theme = 'alabaster'
html_theme_options = {
- 'description': 'Celery module for Invenio.',
+ 'description': 'Celery distributed task queue module for Invenio.',
'github_user': 'inveniosoftware',
'github_repo': 'invenio-celery',
'github_button': False,
diff --git a/docs/configuration.rst b/docs/configuration.rst
new file mode 100644
index 0000000..26981a2
--- /dev/null
+++ b/docs/configuration.rst
@@ -0,0 +1,29 @@
+..
+ This file is part of Invenio.
+ Copyright (C) 2017 CERN.
+
+ Invenio is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General Public License as
+ published by the Free Software Foundation; either version 2 of the
+ License, or (at your option) any later version.
+
+ Invenio is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with Invenio; if not, write to the
+ Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ MA 02111-1307, USA.
+
+ In applying this license, CERN does not
+ waive the privileges and immunities granted to it by virtue of its status
+ as an Intergovernmental Organization or submit itself to any jurisdiction.
+
+
+Configuration
+=============
+
+.. automodule:: invenio_celery.config
+ :members:
diff --git a/docs/index.rst b/docs/index.rst
index 8860da6..546881d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -34,6 +34,7 @@ Invenio-Celery.
:maxdepth: 2
installation
+ configuration
usage
diff --git a/invenio_celery/__init__.py b/invenio_celery/__init__.py
index 7a9fffa..23b5512 100644
--- a/invenio_celery/__init__.py
+++ b/invenio_celery/__init__.py
@@ -22,22 +22,64 @@
# waive the privileges and immunities granted to it by virtue of its status
# as an Intergovernmental Organization or submit itself to any jurisdiction.
-"""Celery module for Invenio.
+"""Celery distributed task queue module for Invenio.
-Invenio-Celery is a core component of Invenio responsible for integrating
-Celery using Flask-CeleryExt and by providing reasonable configuration
-defaults.
+Invenio-Celery is a small discovery layer that takes care of discovering and
+loading tasks from other Invenio modules, as well as providing configuration
+defaults for Celery usage in Invenio. Invenio-Celery relies on Flask-CeleryExt
+for integrating Flask and Celery with application factories.
-Configuration
--------------
+Defining tasks
+--------------
+Invenio modules that wish to define Celery tasks should use the
+``@shared_task`` decorator (usually in ``tasks.py``):
-.. automodule:: invenio_celery.config
- :members:
+.. code-block:: python
-For further details on Celery configuration and Flask-CeleryExt usage see:
+ # mymodule/tasks.py
+ from celery import shared_task
- * http://docs.celeryproject.org/en/latest/configuration.html
- * https://Flask-CeleryExt.readthedocs.io/
+ @shared_task
+ def sum(x, y):
+ return x + y
+
+Additionally the Invenio module should add the task module into the
+``invenio_celery.tasks`` entry point:
+
+.. code-block:: python
+
+ # setup.py
+ setup(
+ # ...
+ entry_points=[
+ 'invenio_celery.tasks' : [
+ 'mymodule = mymodule.tasks'
+ ]
+ ]
+ )
+
+Using tasks
+-----------
+Invenio modules that need to call tasks do not need to do anything special as
+long as the Invenio-Celery extension has been initialized. Hence calling tasks
+is as simple as:
+
+.. code-block:: python
+
+ from mymoudle.tasks import sum
+ result = sum.delay(2, 2)
+
+
+Celery workers
+--------------
+Invenio-Celery hooks into the Celery application loading process so that when
+a worker starts, all the tasks modules defined in ``invenio_celery.tasks`` will
+be imported and cause the tasks to be registered in the worker. Note that this
+only happens on the Celery worker side which needs to know upfront all the
+possible tasks.
+
+For further details on how to setup Celery and define an Celery application
+factory please see `Flask-CeleryExt `_
"""
from __future__ import absolute_import, print_function
diff --git a/invenio_celery/config.py b/invenio_celery/config.py
index c1ae0d3..5e59c26 100644
--- a/invenio_celery/config.py
+++ b/invenio_celery/config.py
@@ -22,7 +22,12 @@
# waive the privileges and immunities granted to it by virtue of its status
# as an Intergovernmental Organization or submit itself to any jurisdiction.
-"""Default configuration values for Celery integration."""
+"""Default configuration values for Celery integration.
+
+For further Celery configuration variables see
+`Celery `_
+documentation.
+"""
BROKER_URL = 'redis://localhost:6379/0'
"""Broker settings."""