Download as
Browse Code »

Commit d128648103d8c9f1a218a904f9df4256548c41bc

Authored by Lucas Moura
Committed by Sergio Oliveira
1 parent 3c820045
Exists in master and in 30 other branches 1.12.x, add_requests_as_dep, celery_service, change-passwd-signal, colab-signals, colab-vcard, colab_search, colab_tag, colab_tag_merge, detach_super_archives, fix-dashboard, fix-message-preview, fix_app_label, fix_header, fixed_gitlab_import, go_to_profile_panel, mobile_user_scalable, paginate-threads, profile_integration, refactor-data-import, remove-gitlab-plugin, removing_namespace, search_block, search_filters, split_screen, startplugin, timestamp_plugins, translation_review, user_regex, validate-passwd

Creating documentation for signals 

Creating sphinx .rst file containing the documentation for a plugin to use the
colab signals structure.

Signed-off-by: Lucas Moura <lucas.moura128@gmail.com>
Signed-off-by: Lucas Kanashiro <kanashiro.duarte@gmail.com>
Showing 1 changed file with 93 additions and 1 deletions   Show diff stats
docs/source/plugindev.rst
  Diff comments   View file @d128648
... ... @@ -6,4 +6,96 @@ Plugin Developer Documentation
6 6  
7 7 Getting Started
8 8 ---------------
9   -.. TODO
  9 +
  10 +Signals
  11 +----------
  12 +
  13 +In order to configure a plugin to able to listen and send signals using Colab
  14 +signals structure, some steps are required:
  15 +
  16 +* Every plugin that needs to handle signals in colab need to use celery in order
  17 + to run taks asynchronously. This is due the fact that every time a handling
  18 + method for a signal is executed, it will be executed as a asynchronously
  19 + celery tasks, in order to not block other colab tasks. To use celery in the
  20 + plugin, file named celery.py needs to be created on the root directory of the
  21 + plugin. An example file can be seen below:
  22 +
  23 +.. code-block:: python
  24 +
  25 + m __future__ import absolute_import
  26 +
  27 + import os
  28 +
  29 + from celery import Celery
  30 +
  31 + # set the default Django settings module for the 'celery' program.
  32 + os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'colab.settings')
  33 +
  34 + from django.conf import settings
  35 +
  36 + app = Celery('colab')
  37 +
  38 + app.config_from_object('django.conf:settings')
  39 + app.autodiscover_tasks(lambda: settings.INSTALLED_APPS)
  40 +
  41 + app.conf.update(
  42 + CELERY_RESULT_BACKEND='djcelery.backends.database:DatabaseBackend',
  43 + )
  44 + app.conf.update(
  45 + CELERY_RESULT_BACKEND='djcelery.backends.cache:CacheBackend',
  46 + )
  47 +
  48 +* The plugin should import the method from colab.signals.tasks in order for the
  49 + plugin to use the necessary method to handle signals
  50 +* In the apps.py file it is necessary to declare a list variable containing all the
  51 + signals that the plugin will dispatch. It is suggested to name the variable
  52 + "registered_signals", but that nomenclature not strictly necessary.
  53 +* It is also necessary to declare a variable containing the name of the plugin
  54 + that will send the signal. It must be said that the name of the plugin cannot
  55 + contain any special character, such as dot or comma. It is suggested to name
  56 + the variable "short_name", but that nomenclature is not strictly
  57 + necessary.
  58 +* In order to actually register the signals, it is necessary to call the method
  59 + register_signal, which require the name of the plugin that is registering the
  60 + signals and a list of signals to be registered as parameters. This method
  61 + should be called on the app method named __init__. Since the plugin class is a
  62 + subclass of AppConfig, the constructor of the parent must be calles as weel.
  63 +
  64 +.. code-block:: ṕython
  65 + def __init__(self, app_name, app_module):
  66 + super(ProxyGitlabAppConfig, self).__init__(app_name, app_module)
  67 + register_signal(self.short_name, self.signals_list)
  68 +
  69 +* In order to listen for a given signal, it is required to create a handling
  70 + method. This method should be located at a file named tasks.py in the same
  71 + directory as the plugins files. It also must be said that this method need to
  72 + receive at least a \*\*kwargs parameter. An example of a handling method can
  73 + be seen below:
  74 +
  75 +.. code-block:: python
  76 + # import app from celery.py
  77 +
  78 + @app.task(bind=True)
  79 + def handling_method(self, **kwargs):
  80 + # DO SOMETHING
  81 +
  82 +* With signals registered and handling method defined you must connect them.
  83 + To do it you must call connect_signal passing signal name, sender and handling
  84 + method as arguments. This calling must be into ready function in apps.py, as
  85 + you can see below:
  86 +
  87 +.. code-block:: python
  88 + def ready(self):
  89 + connect_signal(self.signal_name, self.sender, handling_method)
  90 +
  91 +* To send a broadcast signal you must call send method anywhere passing signal name
  92 + and sender as arguments. If necessary you can pass another parameters in
  93 + \*\*kwargs. As you can see below:
  94 +
  95 +.. code-block:: python
  96 + send(signal_name, sender)
  97 +
  98 +* If you want to run celery manually to make some tests, you should execute:
  99 +
  100 +.. code-block:: shell
  101 + celery -A colab worker --loglevel=debug
... ...