docs: updated integrations docs fix #4137

docs/integrations/hipchat.rst

@@ -1,19 +1,14 b''
 .. _integrations-hipchat:
 
 Hipchat integration
 ===================
 
-In order to set a hipchat integration up it is necessary to obtain the Hipchat
+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`
+1. Log into Hipchat (https://your-hipchat.hipchat.com/)
+2. Go to *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`.
+Hipchat will create a URL for you to use in your integration as outlined in
+:ref:`creating-integrations`.
  No newline at end of file

docs/integrations/integrations.rst

@@ -1,50 +1,52 b''
 .. _integrations:
 
 Integrations
 ------------
 
-Rhodecode supports integrations with external services for various events
+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.
+can be added at the same time; this is useful for posting different events to
+different Slack channels, for example.
 
 Supported integrations
 ^^^^^^^^^^^^^^^^^^^^^^
 
 ============================    ============    =====================================
 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-email`       |RCEEshort|     Send repo push commits by email
 :ref:`integrations-redmine`     |RCEEshort|     Close/Resolve/Reference redmine issues
 :ref:`integrations-jira`        |RCEEshort|     Close/Resolve/Reference JIRA issues
 ============================    ============    =====================================
 
 .. _creating-integrations:
 
-Creating an integration
+Creating an Integration
 ^^^^^^^^^^^^^^^^^^^^^^^
 
 Integrations can be added globally via the admin UI:
 
 :menuselection:`Admin --> Integrations`
 
-or per repository in the repository settings:
+or per repository in each repository's settings:
 
 :menuselection:`Admin --> Repositories --> Edit --> Integrations`
 
-To create an integration, select the type from the list of types in the
-`Create an integration` section.
+To create an integration, select the type from the list in the *Create New
+Integration* section.
 
-The `Current integrations` section shows existing integrations that have been
-created along with their type (eg. slack) and enabled status.
+The *Current Integrations* section shows existing integrations that have been
+created along with their type (eg. Slack) and enabled status.
+
+See pages specific to each type of integration for more instructions:
 
 .. toctree::
 
    slack
    hipchat
    redmine
    jira
    webhook

docs/integrations/jira.rst

@@ -1,26 +1,27 b''
 .. _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.
+    JIRA integration is only available in |RCEE|.
+
 
 .. important::
 
-    JIRA integration is only available in |RCEE|.
+    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.
 
 
 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``.
+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.
+In order to apply a status to a JIRA issue, it is necessary to find the
+transition status id in the *Workflow* section of JIRA.
 
-Once you have the transition status id, create a ``jira`` integration in
-:ref:`creating-integrations`.
+Once you have the transition status id, you can create a JIRA integration
+as outlined in :ref:`creating-integrations`.

docs/integrations/redmine.rst

@@ -1,25 +1,28 b''
 .. _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.
+    Redmine integration is only available in |RCEE|.
+
 
 .. important::
 
-    Redmine integration is only available in |RCEE|.
+    In order to make issue numbers clickable in commit messages, see the section
+    :ref:`rhodecode-issue-trackers-ref`. Redmine integration is specifically for
+    altering Redmine issues.
 
-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.
+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".
 
-Once you have the api key, create a ``redmine`` integration in
+To set a Redmine integration up, it is first necessary to obtain a Redmine API
+key. This can be found under *My Account* in the Redmine application.
+You may have to enable API Access in Redmine settings if it is not already
+available.
+
+Once you have the API key, create a Redmine integration as outlined in
 :ref:`creating-integrations`.

docs/integrations/slack.rst

@@ -1,13 +1,21 b''
 .. _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:
+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`.
+Select the channel you would like to use, and Slack will provide you with the
+webhook URL for configuration.
+
+You can now create a Slack integration as outlined in
+:ref:`creating-integrations`.
+
+.. note::
+    Some settings in the RhodeCode admin are identical to the options within the
+    Slack integration. For example, if notifications are to be sent in a private
+    chat, leave the "Channel" field blank. Likewise, the Emoji option within
+    RhodeCode can override the one set in the Slack admin.
  No newline at end of file

docs/integrations/webhook.rst

@@ -1,10 +1,12 b''
 .. _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`.
+To create a webhook integration, select "webhook" in the integration settings
+and use the url and key from your custom webhook. See
+:ref:`creating-integrations` for additional instructions.
  No newline at end of file

docs/issue-trackers/issue-trackers.rst

@@ -1,82 +1,81 b''
 .. _rhodecode-issue-trackers-ref:
 
 Issue Tracker Integration
 =========================
 
 You can set an issue tracker connection in two ways with |RCE|.
 
-* At instance level you can set a default issue tracker.
-* At |repo| level you can configure an integration with a different issue
+* At the instance level, you can set a default issue tracker.
+* At the |repo| level, you can configure an integration with a different issue
   tracker.
 
-To integrate |RCM| with an issue tracker you need to define a regular
-expression that will fetch the issue ID stored in commit messages and replace
+To integrate |RCM| with an issue tracker, you need to define a regular
+expression that will fetch the issue ID stored in commit messages, and replace
 it with a URL. This enables |RCE| to generate a link matching each issue to the
 target |repo|.
 
 Default Issue Tracker Configuration
 -----------------------------------
 
 To integrate your issue tracker, use the following steps:
 
 1. Open :menuselection:`Admin --> Settings --> Issue Tracker`.
 2. In the new entry field, enter the following information:
 
     * :guilabel:`Description`: A name for this set of rules.
     * :guilabel:`Pattern`: The regular expression that will match issues
       tagged in commit messages, or more see :ref:`issue-tr-eg-ref`.
     * :guilabel:`URL`: The URL to your issue tracker.
     * :guilabel:`Prefix`: The prefix with which you want to mark issues.
 
 3. Select **Add** so save the rule to your issue tracker configuration.
 
 Repository Issue Tracker Configuration
 --------------------------------------
 
-You can configure specific |repos| to use a different issue tracker if
-you need to connect to a non-default one. See the instructions in
-:ref:`repo-it`
+You can configure specific |repos| to use a different issue tracker than the
+default one. See the instructions in :ref:`repo-it`
 
 .. _issue-tr-eg-ref:
 
 Jira Integration
 ----------------
 
 * Regex = ``(?:^#|\s#)(\w+-\d+)``
 * URL = ``https://myissueserver.com/issue/${id}``
 * Issue Prefix = ``#``
 
 Confluence (Wiki)
 -----------------
 
 * Regex = ``(?:conf-)([A-Z0-9]+)``
 * URL = ``https://example.atlassian.net/display/wiki/${id}/${repo_name}``
 * issue prefix = ``CONF-``
 
 Redmine Integration
 -------------------
 
 * Regex = ``(issue-+\d+)``
 * URL = ``https://myissueserver.com/redmine/issue/${id}``
 * Issue Prefix = ``issue-``
 
 Redmine (wiki)
 --------------
 
 * Regex = ``(?:wiki-)([a-zA-Z0-9]+)``
 * URL = ``https://example.com/redmine/projects/wiki/${repo_name}``
 * Issue prefix = ``Issue-``
 
 Pivotal Tracker
 ---------------
 
 * Regex = ``(?:pivot-)(?<project_id>\d+)-(?<story>\d+)``
 * URL = ``https://www.pivotaltracker.com/s/projects/${project_id}/stories/${story}``
 * Issue prefix = ``Piv-``
 
 Trello
 ------
 
 * Regex = ``(?:trello-)(?<card_id>[a-zA-Z0-9]+)``
 * URL = ``https://trello.com/example.com/${card_id}``
 * Issue prefix = ``Trello-``