docs: updated docs for integrations, fixes #4137

* added docs for jira, hipchat, redmine, jira, webhook integrations
* moved old integrations/rcextensions docs to "hooks & extensions"

docs/extensions/extensions-hooks.rst

@@ -0,0 +1,25
+.. _extensions-hooks-ref:
+
+Extensions & Hooks
+==================
+
+The extensions & hooks section references three concepts regularly,
+so to clarify what is meant each time, read the following definitions:
+
+* **Plugin**: A Plugin is software that adds a specific feature to
+  an existing software application.
+* **Extension**: An extension extends the capabilities of,
+  or the data available to, an existing software application.
+* **Hook**: A hook intercepts function calls, messages, or events passed
+  between software components and can be used to trigger plugins, or their
+  extensions.
+
+.. toctree::
+
+   rcx
+   install-ext
+   config-ext
+   extensions
+   hooks
+   full-blown-example
+   int-slack

docs/integrations/hipchat.rst

@@ -0,0 +1,19
+.. _integrations-hipchat:
+
+Hipchat integration
+===================
+
+In order to set a hipchat integration up it is necessary to obtain the Hipchat
+service url by:
+
+1. Login to Hipchat (https://www.hipchat.com/)
+2. Goto `Integrations` -> `Build your own`
+3. Select a room to post notifications to and save it
+
+Once the integration is setup on hipchat you should have a url of the
+form: `
+which can be used in :ref:`creating-integrations`
+
+Once you have set up a Hipchat webhook integrations url of the form:
+``https://yourapp.hipchat.com/v2/room/123456/notification?auth_token=...``,
+create a ``hipchat`` integration in :ref:`creating-integrations`.

docs/integrations/jira.rst

@@ -0,0 +1,26
+.. _integrations-jira:
+
+JIRA integration
+================
+
+.. important::
+
+    In order to make issue numbers clickable in commit messages see the
+    :ref:`rhodecode-issue-trackers-ref` section. The JIRA integration
+    only deals with altering JIRA issues.
+
+.. important::
+
+    JIRA integration is only available in |RCEE|.
+
+
+The JIRA integration allows you to reference and change issue statuses in
+JIRA directly from commit messages using commit message patterns such as
+``fixes #JIRA-235`` in order to change the status of issue JIRA-235 to
+eg. ``Resolved``.
+
+In order to apply a status to a JIRA issue it is necessary to find out the
+transition status id which can be found in the Workflow section of JIRA.
+
+Once you have the transition status id, create a ``jira`` integration in
+:ref:`creating-integrations`.

docs/integrations/redmine.rst

@@ -0,0 +1,25
+.. _integrations-redmine:
+
+Redmine integration
+===================
+
+.. important::
+
+    In order to make issue numbers clickable in commit messages see the
+    :ref:`rhodecode-issue-trackers-ref` section. The Redmine integration
+    only deals with altering Redmine issues.
+
+.. important::
+
+    Redmine integration is only available in |RCEE|.
+
+The Redmine integration allows you to reference and change issue statuses in
+Redmine directly from commit messages using commit message patterns such as
+``fixes #235`` in order to change the status of issue 235 to eg. ``Resolved``
+
+To set a Redmine integration up it is first necessary to obtain a Redmine api
+key. This can be found in ``My Account`` in the Redmine application.
+If it is not there, you may have to enable API Access in Redmine settings.
+
+Once you have the api key, create a ``redmine`` integration in
+:ref:`creating-integrations`.

docs/integrations/slack.rst

@@ -0,0 +1,13
+.. _integrations-slack:
+
+Slack integration
+=================
+
+To set a Slack integration up it is first necessary to set up a Slack webhook api
+endpoint for your slack channel, this can be done at:
+
+https://my.slack.com/services/new/incoming-webhook/
+
+Once you have set up a Slack webhook integrations url of the
+form: ``https://hooks.slack.com/services/...``, create a ``slack`` integration
+in :ref:`creating-integrations`.

docs/integrations/webhook.rst

@@ -0,0 +1,10
+.. _integrations-webhook:
+
+Webhook integration
+===================
+
+The Webhook integration allows you to POST events such as repository pushes
+or pull requests to a custom http endpoint as a json dict with details of the
+event.
+
+To create a webhook integration select ``webhook`` in :ref:`creating-integrations`.

docs/admin/backup-restore.rst

@@ -121,7 +121,7
   :ref:`indexing-ref` section for details.
 * To reconfigure any extensions, copy the backed up extensions into the
   :file:`/home/{user}/.rccontrol/{instance-id}/rcextensions` and also specify
-  any custom hooks if necessary. See the :ref:`integrations-ref` section for
+  any custom hooks if necessary. See the :ref:`extensions-hooks-ref` section for
   details.
 
 .. _Schrödinger's Backup: http://novabackup.novastor.com/blog/schrodingers-backup-good-bad-backup/

docs/admin/repo-extra-fields.rst

@@ -32,7 +32,7
 -------------
 
 To use the extra fields in an extension, see the example below. For more
-information and examples, see the :ref:`integrations-ref` section.
+information and examples, see the :ref:`extensions-hooks-ref` section.
 
 .. code-block:: python
 

docs/code-review/code-review.rst

@@ -14,7 +14,7
 
 You can also use the |RCE| API set up continuous integration servers to leave
 comments from a test suite. See the :ref:`api` and
-:ref:`integrations-ref` sections for examples on how to set this up.
+:ref:`extensions-hooks-ref` sections for examples on how to set this up.
 
 .. toctree::
 

docs/common.py

@@ -6,6 +6,8
 .. |AE| replace:: Appenlight
 .. |authtoken| replace:: Authentication Token
 .. |authtokens| replace:: **Auth Tokens**
+.. |RCCEshort| replace:: Community
+.. |RCEEshort| replace:: Enterprise
 .. |git| replace:: Git
 .. |hg| replace:: Mercurial
 .. |svn| replace:: Subversion

docs/index.rst

@@ -58,6 +58,7
    collaboration/review-notifications
    collaboration/pull-requests
    code-review/code-review
+   integrations/integrations
 
 .. toctree::
    :maxdepth: 1
@@ -65,7 +66,7
 
    api/api
    tools/rhodecode-tools
-   integrations/integrations
+   extensions/extensions-hooks
    contributing/contributing
 
 .. toctree::

docs/integrations/integrations.rst

@@ -1,25 +1,49
-.. _integrations-ref:
+.. _integrations:
+
+Integrations
+------------
 
-Integrations and Extensions
-===========================
+Rhodecode supports integrations with external services for various events
+such as commit pushes and pull requests. Multiple integrations of the same type
+(eg. slack) can be added at the same time which is useful for example to post
+different events to different slack channels.
 
-The integrations section references three concepts regularly,
-so to clarify what is meant each time, read the following definitions:
+Supported integrations
+^^^^^^^^^^^^^^^^^^^^^^
 
-* **Plugin**: A Plugin is software that adds a specific feature to
-  an existing software application.
-* **Extension**: An extension extends the capabilities of,
-  or the data available to, an existing software application.
-* **Hook**: A hook intercepts function calls, messages, or events passed
-  between software components and can be used to trigger plugins, or their
-  extensions.
+============================    ============    =====================================
+Type/Name                       |RC| Edition    Description
+============================    ============    =====================================
+:ref:`integrations-slack`       |RCCEshort|     https://slack.com/
+:ref:`integrations-hipchat`     |RCCEshort|     https://www.hipchat.com/
+:ref:`integrations-webhook`     |RCCEshort|     POST events as `json` to a custom url
+:ref:`integrations-redmine`     |RCEEshort|     Close/Resolve/Reference redmine issues
+:ref:`integrations-jira`        |RCEEshort|     Close/Resolve/Reference JIRA issues
+============================    ============    =====================================
+
+.. _creating-integrations:
+
+Creating an integration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Integrations can be added globally via the admin UI:
+
+:menuselection:`Admin --> Integrations`
+
+or per repository in the repository settings:
+
+:menuselection:`Admin --> Repositories --> Edit --> Integrations`
+
+To create an integration, select the type from the list of types in the
+`Create an integration` section.
+
+The `Current integrations` section shows existing integrations that have been
+created along with their type (eg. slack) and enabled status.
 
 .. toctree::
 
-   rcx
-   install-ext
-   config-ext
-   extensions
-   hooks
-   full-blown-example
-   int-slack
+   slack
+   hipchat
+   redmine
+   jira
+   webhook

docs/tools/tools-cli.rst

@@ -301,7 +301,7
 
     \ - -plugins
          Add plugins to your |RCE| installation. See the
-         :ref:`integrations-ref` section for more details.
+         :ref:`extensions-hooks-ref` section for more details.
 
     \ - -version
          Display your |RCT| version.