docs: Improved Slack Action documentation (#142)

* Improve Slack Action Docs * Add Guide and Suggestions implemented Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Suggestions implemented #2 Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Changes implemented as suggested #3 Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Changes made as suggested #3 Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Add Slack Credentials Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Add reference to Getting started Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Changes implemented as suggested #2 Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Changes implemented as suggested #3 Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Final changes made Signed-off-by: Vipul Gupta (@vipulgupta2048) <[email protected]> * Update docs/source/configuring-slack-for-spidermon.rst Co-Authored-By: Adrián Chaves <[email protected]>
scrapinghub · Sep 3, 2019 · f0bc473 · f0bc473
1 parent 4c5c392
commit f0bc473
Show file tree

Hide file tree

Showing 4 changed files with 43 additions and 6 deletions.
diff --git a/docs/source/actions.rst b/docs/source/actions.rst
@@ -205,6 +205,8 @@ A notification will look like the following one:
  :scale: 50 %
  :alt: Slack Notification
 
+Follow :ref:`these steps <configuring-slack-bot>` to configure your Slack bot.
+
 The following settings are the minimum needed to make this action works:
 
 .. _SPIDERMON_SLACK_RECIPIENTS:
@@ -219,12 +221,18 @@ List of recipients of the message. It could be a channel or an user.
 SPIDERMON_SLACK_SENDER_NAME
 ---------------------------
 
+Username of your bot.
+
 .. _SPIDERMON_SLACK_SENDER_TOKEN:
 
 SPIDERMON_SLACK_SENDER_TOKEN
 ----------------------------
 
-Your `Slack token`_.
+`Bot User OAuth Access Token` of your bot.
+
+.. warning::
+
+ Be careful when using bot user tokens in Spidermon. Do not publish bot user tokens in public code repositories.
 
 Other settings available:
 
@@ -289,9 +297,6 @@ SPIDERMON_SLACK_NOTIFIER_REPORT_INDEX
 
 .. _`Slack`: https://slack.com/
 .. _`Slack credentials`: https://api.slack.com/docs/token-types
-.. _`Slack token`: https://api.slack.com/docs/token-types
-
-.. _actions-job-tags:
 
 Job tags action
 ===============

diff --git a/docs/source/configuring-slack-for-spidermon.rst b/docs/source/configuring-slack-for-spidermon.rst
@@ -0,0 +1,31 @@
+.. _configuring-slack-bot:
+
+====================================
+Configure a Slack bot for Spidermon
+====================================
+
+What are bots?
+==============
+
+A bot is a type of Slack App designed to interact with users via conversation.
+
+To work with `Slack Actions <https://spidermon.readthedocs.io/en/latest/actions.html#slack-action>`_, you will need a Slack bot which would send `notifications <https://spidermon.readthedocs.io/en/latest/getting-started.html#slack-notifications>`_ to your Slack workspace from Spidermon.
+
+Steps
+=====
+
+.. note:
+ You need to be the `owner/admin <https://get.slack.help/hc/en-us/articles/201314026-Understanding-roles-permissions-inside-Slack>`_ of the `Slack workspace <https://get.slack.help/hc/en-us/articles/206845317-Create-a-Slack-workspace>`_ for which you are trying to create a bot.
+
+1. `Create a Slack bot <https://get.slack.help/hc/en-us/articles/115005265703-Create-a-bot-for-your-workspace>`_.
+
+2. Once your bot is created, you can find Bot User OAuth Access Token in its settings. This `Bot User OAuth Access Token` is what we use for ``SPIDERMON_SLACK_SENDER_TOKEN``.
+
+3. Lastly, add your Slack credentials to your Scrapy project's settings.
+
+.. code-block:: python
+
+ # settings.py
+ SPIDERMON_SLACK_SENDER_TOKEN = 'YOUR_BOT_USER_OAUTH_ACCESS_TOKEN'
+ SPIDERMON_SLACK_SENDER_NAME = 'YOUR_BOT_USERNAME'
+ SPIDERMON_SLACK_RECIPIENTS = ['@yourself', '#yourprojectchannel']
diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
@@ -209,8 +209,8 @@ a Slack channel using a bot when a monitor fails.
  SendSlackMessageSpiderFinished,
  ]
 
-After enabling the action, you need to provide the `Slack credentials`_ in your `settings.py`
-file as follows:
+After enabling the action, you need to provide the `Slack
+credentials`_. You can access the required credentials by following these steps to :ref:`configuring-slack-bot`. Later, fill the credentials in your `settings.py` as follows:
 
 .. code-block:: python
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -34,5 +34,6 @@ Contents
  stats-collection
  expression-monitors
  settings
+ configuring-slack-for-spidermon
  actions
  changelog