diff --git a/docs/source/plugindev.rst b/docs/source/plugindev.rst index 1a26e12..d650e3e 100644 --- a/docs/source/plugindev.rst +++ b/docs/source/plugindev.rst @@ -6,4 +6,96 @@ Plugin Developer Documentation Getting Started --------------- -.. TODO + +Signals +---------- + +In order to configure a plugin to able to listen and send signals using Colab +signals structure, some steps are required: + +* Every plugin that needs to handle signals in colab need to use celery in order + to run taks asynchronously. This is due the fact that every time a handling + method for a signal is executed, it will be executed as a asynchronously + celery tasks, in order to not block other colab tasks. To use celery in the + plugin, file named celery.py needs to be created on the root directory of the + plugin. An example file can be seen below: + +.. code-block:: python + + m __future__ import absolute_import + + import os + + from celery import Celery + + # set the default Django settings module for the 'celery' program. + os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'colab.settings') + + from django.conf import settings + + app = Celery('colab') + + app.config_from_object('django.conf:settings') + app.autodiscover_tasks(lambda: settings.INSTALLED_APPS) + + app.conf.update( + CELERY_RESULT_BACKEND='djcelery.backends.database:DatabaseBackend', + ) + app.conf.update( + CELERY_RESULT_BACKEND='djcelery.backends.cache:CacheBackend', + ) + +* The plugin should import the method from colab.signals.tasks in order for the + plugin to use the necessary method to handle signals +* In the apps.py file it is necessary to declare a list variable containing all the + signals that the plugin will dispatch. It is suggested to name the variable + "registered_signals", but that nomenclature not strictly necessary. +* It is also necessary to declare a variable containing the name of the plugin + that will send the signal. It must be said that the name of the plugin cannot + contain any special character, such as dot or comma. It is suggested to name + the variable "short_name", but that nomenclature is not strictly + necessary. +* In order to actually register the signals, it is necessary to call the method + register_signal, which require the name of the plugin that is registering the + signals and a list of signals to be registered as parameters. This method + should be called on the app method named __init__. Since the plugin class is a + subclass of AppConfig, the constructor of the parent must be calles as weel. + +.. code-block:: ṕython + def __init__(self, app_name, app_module): + super(ProxyGitlabAppConfig, self).__init__(app_name, app_module) + register_signal(self.short_name, self.signals_list) + +* In order to listen for a given signal, it is required to create a handling + method. This method should be located at a file named tasks.py in the same + directory as the plugins files. It also must be said that this method need to + receive at least a \*\*kwargs parameter. An example of a handling method can + be seen below: + +.. code-block:: python + # import app from celery.py + + @app.task(bind=True) + def handling_method(self, **kwargs): + # DO SOMETHING + +* With signals registered and handling method defined you must connect them. + To do it you must call connect_signal passing signal name, sender and handling + method as arguments. This calling must be into ready function in apps.py, as + you can see below: + +.. code-block:: python + def ready(self): + connect_signal(self.signal_name, self.sender, handling_method) + +* To send a broadcast signal you must call send method anywhere passing signal name + and sender as arguments. If necessary you can pass another parameters in + \*\*kwargs. As you can see below: + +.. code-block:: python + send(signal_name, sender) + +* If you want to run celery manually to make some tests, you should execute: + +.. code-block:: shell + celery -A colab worker --loglevel=debug -- libgit2 0.21.2