Merge pull request #71 from acsone/new-readme-sbi

README as fragments

queue_job/README.rst

@@ -1,11 +1,27 @@
-.. image:: https://img.shields.io/badge/licence-AGPL--3-blue.svg
-   :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
-   :alt: License: AGPL-3
-
 =========
 Job Queue
 =========
 
+.. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Mature-brightgreen.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Mature
+.. |badge2| image:: https://img.shields.io/badge/licence-AGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
+    :alt: License: AGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fqueue-lightgray.png?logo=github
+    :target: https://github.com/OCA/queue/tree/11.0/queue_job
+    :alt: OCA/queue
+.. |badge4| image:: https://img.shields.io/badge/runbot-Try%20me-875A7B.png
+    :target: https://runbot.odoo-community.org/runbot/230/11.0
+    :alt: Try me on Runbot
+
+|badge1| |badge2| |badge3| |badge4| 
+
 This addon adds an integrated Job Queue to Odoo.
 
 It allows to postpone method calls executed asynchronously.
@@ -57,6 +73,10 @@ Features:
 * Related Actions: link an action on the job view, such as open the record
   concerned by the job
 
+**Table of contents**
+
+.. contents::
+   :local:
 
 Installation
 ============
@@ -68,16 +88,15 @@ Configuration
 
 * Using environment variables and command line:
 
- * Adjust environment variables (optional):
-
-  - ``ODOO_QUEUE_JOB_CHANNELS=root:4``
+  * Adjust environment variables (optional):
 
-   - or any other channels configuration. The default is ``root:1``
+    - ``ODOO_QUEUE_JOB_CHANNELS=root:4`` or any other channels configuration. 
+      The default is ``root:1``
 
-  - if ``xmlrpc_port`` is not set: ``ODOO_QUEUE_JOB_PORT=8069``
+    - if ``xmlrpc_port`` is not set: ``ODOO_QUEUE_JOB_PORT=8069``
 
- * Start Odoo with ``--load=web,queue_job``
-   and ``--workers`` greater than 1. [1]_
+  * Start Odoo with ``--load=web,queue_job``
+    and ``--workers`` greater than 1. [1]_
 
 
 * Using the Odoo configuration file:
@@ -95,7 +114,7 @@ Configuration
 
 * Confirm the runner is starting correctly by checking the odoo log file:
 
-.. code-block:: none
+.. code-block::
 
   ...INFO...queue_job.jobrunner.runner: starting
   ...INFO...queue_job.jobrunner.runner: initializing database connections
@@ -118,10 +137,6 @@ To use this module, you need to:
 
 #. Go to ``Job Queue`` menu
 
-.. image:: https://odoo-community.org/website/image/ir.attachment/5784_f2813bd/datas
-   :alt: Try me on Runbot
-   :target: https://runbot.odoo-community.org/runbot/230/10.0
-
 Known issues / Roadmap
 ======================
 
@@ -147,41 +162,42 @@ Known issues / Roadmap
 Bug Tracker
 ===========
 
-Bugs are tracked on `GitHub Issues
-<https://github.com/OCA/queue/issues>`_. In case of trouble, please
-check there if your issue has already been reported. If you spotted it first,
-help us smashing it by providing a detailed and welcomed feedback.
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/queue/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us smashing it by providing a detailed and welcomed feedback.
+
+Do not contact contributors directly about support or help with technical issues.
 
 Credits
 =======
 
-Images
-------
-
-* Odoo Community Association: `Icon <https://github.com/OCA/maintainer-tools/blob/master/template/module/static/description/icon.svg>`_.
+Authors
+~~~~~~~
 
-Contributors
-------------
+* Camptocamp
+* ACSONE SA/NV
 
-* Guewen Baconnier <[email protected]>
-* Stéphane Bidoul <[email protected]>
-* Matthieu Dietrich <[email protected]>
-* Jos De Graeve <[email protected]>
-* David Lefever <[email protected]>
-* Laurent Mignon <[email protected]>
-* Laetitia Gangloff <[email protected]>
+Maintainers
+~~~~~~~~~~~
 
-Maintainer
-----------
+This module is maintained by the OCA.
 
 .. image:: https://odoo-community.org/logo.png
    :alt: Odoo Community Association
    :target: https://odoo-community.org
 
-This module is maintained by the OCA.
-
 OCA, or the Odoo Community Association, is a nonprofit organization whose
 mission is to support the collaborative development of Odoo features and
 promote its widespread use.
 
-To contribute to this module, please visit https://odoo-community.org.
+.. |maintainer-guewen| image:: https://github.com/guewen.png?size=40px
+    :target: https://github.com/guewen
+    :alt: guewen
+
+Current `maintainer <https://odoo-community.org/page/maintainer-role>`_:
+
+|maintainer-guewen| 
+
+This module is part of the `OCA/queue <https://github.com/OCA/queue/tree/11.0/queue_job>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.

queue_job/__manifest__.py

@@ -20,4 +20,6 @@
           'data/queue_data.xml',
           ],
  'installable': True,
+ 'development_status': 'Mature',
+ 'maintainers': ['guewen'],
  }

queue_job/readme/CONFIGURE.rst

@@ -0,0 +1,43 @@
+* Using environment variables and command line:
+
+  * Adjust environment variables (optional):
+
+    - ``ODOO_QUEUE_JOB_CHANNELS=root:4`` or any other channels configuration. 
+      The default is ``root:1``
+
+    - if ``xmlrpc_port`` is not set: ``ODOO_QUEUE_JOB_PORT=8069``
+
+  * Start Odoo with ``--load=web,queue_job``
+    and ``--workers`` greater than 1. [1]_
+
+
+* Using the Odoo configuration file:
+
+.. code-block:: ini
+
+  [options]
+  (...)
+  workers = 4
+  server_wide_modules = web,queue_job
+
+  (...)
+  [queue_job]
+  channels = root:4
+
+* Confirm the runner is starting correctly by checking the odoo log file:
+
+.. code-block::
+
+  ...INFO...queue_job.jobrunner.runner: starting
+  ...INFO...queue_job.jobrunner.runner: initializing database connections
+  ...INFO...queue_job.jobrunner.runner: queue job runner ready for db <dbname>
+  ...INFO...queue_job.jobrunner.runner: database connections ready
+
+* Create jobs (eg using ``base_import_async``) and observe they
+  start immediately and in parallel.
+
+* Tip: to enable debug logging for the queue job, use
+  ``--log-handler=odoo.addons.queue_job:DEBUG``
+
+.. [1] It works with the threaded Odoo server too, although this way
+       of running Odoo is obviously not for production purposes.

queue_job/readme/DESCRIPTION.rst

@@ -0,0 +1,50 @@
+This addon adds an integrated Job Queue to Odoo.
+
+It allows to postpone method calls executed asynchronously.
+
+Jobs are executed in the background by a ``Jobrunner``, in their own transaction.
+
+Example:
+
+.. code-block:: python
+
+  from odoo import models, fields, api
+  from odoo.addons.queue_job.job import job
+
+  class MyModel(models.Model):
+     _name = 'my.model'
+
+     @api.multi
+     @job
+     def my_method(self, a, k=None):
+         _logger.info('executed with a: %s and k: %s', a, k)
+
+
+  class MyOtherModel(models.Model):
+      _name = 'my.other.model'
+
+      @api.multi
+      def button_do_stuff(self):
+          self.env['my.model'].with_delay().my_method('a', k=2)
+
+
+In the snippet of code above, when we call ``button_do_stuff``, a job capturing
+the method and arguments will be postponed.  It will be executed as soon as the
+Jobrunner has a free bucket, which can be instantaneous if no other job is
+running.
+
+
+Features:
+
+* Views for jobs, jobs are stored in PostgreSQL
+* Jobrunner: execute the jobs, highly efficient thanks to PostgreSQL's NOTIFY
+* Channels: give a capacity for the root channel and its sub-channels and
+  segregate jobs in them. Allow for instance to restrict heavy jobs to be
+  executed one at a time while little ones are executed 4 at a times.
+* Retries: Ability to retry jobs by raising a type of exception
+* Retry Pattern: the 3 first tries, retry after 10 seconds, the 5 next tries,
+  retry after 1 minutes, ...
+* Job properties: priorities, estimated time of arrival (ETA), custom
+  description, number of retries
+* Related Actions: link an action on the job view, such as open the record
+  concerned by the job

queue_job/readme/INSTALL.rst

@@ -0,0 +1 @@
+Be sure to have the ``requests`` library.

queue_job/readme/ROADMAP.rst

@@ -0,0 +1,18 @@
+* After creating a new database or installing ``queue_job`` on an
+  existing database, Odoo must be restarted for the runner to detect it.
+
+* When Odoo shuts down normally, it waits for running jobs to finish.
+  However, when the Odoo server crashes or is otherwise force-stopped,
+  running jobs are interrupted while the runner has no chance to know
+  they have been aborted. In such situations, jobs may remain in
+  ``started`` or ``enqueued`` state after the Odoo server is halted.
+  Since the runner has no way to know if they are actually running or
+  not, and does not know for sure if it is safe to restart the jobs,
+  it does not attempt to restart them automatically. Such stale jobs
+  therefore fill the running queue and prevent other jobs to start.
+  You must therefore requeue them manually, either from the Jobs view,
+  or by running the following SQL statement *before starting Odoo*:
+
+.. code-block:: sql
+
+  update queue_job set state='pending' where state in ('started', 'enqueued')

queue_job/readme/USAGE.rst

@@ -0,0 +1,3 @@
+To use this module, you need to:
+
+#. Go to ``Job Queue`` menu