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>

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>
Lucas Moura · Sergio Oliveira
1 parent 3c820045
Showing 1 changed file with 93 additions and 1 deletions Show diff stats
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
	@@ -6,4 +6,96 @@ Plugin Developer Documentation		@@ -6,4 +6,96 @@ Plugin Developer Documentation
6		6
7	Getting Started	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