Flesh out intro tutorial

posita · Apr 18, 2018 · 296d38a · 296d38a
1 parent 45c38d0
commit 296d38a
Show file tree

Hide file tree

Showing 9 changed files with 77 additions and 4 deletions.
diff --git a/docs/img/django_add_watcher.png b/docs/img/django_add_watcher.png
diff --git a/docs/img/slack_app_authorize.png b/docs/img/slack_app_authorize.png
diff --git a/docs/img/slack_app_install.png b/docs/img/slack_app_install.png
diff --git a/docs/img/slack_app_oauth_scopes.png b/docs/img/slack_app_oauth_scopes.png
diff --git a/docs/img/slack_app_oauth_token.png b/docs/img/slack_app_oauth_token.png
diff --git a/docs/img/slack_app_verification_token.png b/docs/img/slack_app_verification_token.png
diff --git a/docs/img/slack_event_message.png b/docs/img/slack_event_message.png
diff --git a/docs/intro.rst b/docs/intro.rst
@@ -97,9 +97,81 @@ See `the docs <http://django-fernet-fields.readthedocs.io/en/latest/#keys>`__ fo
 Slack App and Watcher Setup
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-For illustration, we'll create a `workspace-based Slack app <https://api.slack.com/docs/token-types#workspace>`__, but we could just as easily use a traditional one.
+#. Create a `legacy Slack app <https://api.slack.com/apps?new_app=1>`__ or a new `Slack app <https://api.slack.com/apps?new_app_token=1>`__.
 
-TODO: Finish this section.
+#. Once created, navigate to the ``Basic Information`` section and copy the ``Verification Token`` (e.g., ``NS3PYxg1QR1l7s2G0fRDZ8uK``):
+
+   .. image:: img/slack_app_verification_token.png
+      :alt: Slack App verification Token
+
+   This is what you'll use as the ``EMOJIWATCH['slack_verification_token']`` Django setting.
+
+#. Add ``chat:write:bot`` (or ``chat:write``) and the ``emoji:read`` scopes to your app:
+
+   .. image:: img/slack_app_oauth_scopes.png
+      :alt: Slack App OAuth scopes
+
+#. Navigate to the ``OAuth & Permission`` section.
+   If necessary, click ``Install App to Workspace``:
+
+   .. image:: img/slack_app_install.png
+      :alt: Slack App installation
+
+   You'll be asked to authorize your new app in your workspace:
+
+   .. image:: img/slack_app_authorize.png
+      :alt: Slack App authorization
+
+   Click ``Authorize``.
+
+#. Copy the ``OAuth Access Token`` (e.g., ``xoxp-3168...db0b5``):
+
+   .. image:: img/slack_app_oauth_token.png
+      :alt: Slack App OAuth token
+
+   This is what you'll use as the ``EMOJIWATCH['slack_AUTH_token']`` Django setting.
+
+#. If you haven't already, install ``emojiwatch`` into your Django project.
+   (See `Django`_ installation above.)
+   Navigate to your Django project's admin interface and add a new ``Slack Workspace Emoji Watcher`` with your Slack team ID and the channel ID to which you'd like Emojiwatch to post messages:
+
+   .. image:: img/django_add_watcher.png
+      :alt: Add a watcher
+
+   Your Slack team ID can be determined by navigating to any channel within your workspace, and looking at ``boot_data.team_id`` in your browser's JavaScript console:
+
+   .. code-block:: console
+
+       >> boot_data.team_id
+       "T4P09SCHKT"
+
+   Your Slack channel ID can be found in the URL when navigating to that channel:
+
+   .. code-block:: console
+
+       https://<workspace-name>.slack.com/messages/C8VSYSEQ22/details/
+                                                   ^^^^^^^^^^
+
+#. You can test that it's working via ``curl``:
+
+   .. code-block:: console
+
+       curl --verbose --data '{
+         "token": "NS3PYxg1QR1l7s2G0fRDZ8uK",
+         "team_id": "T4P09SCHKT",
+         "type": "event_callback",
+         "event": {
+           "type": "emoji_changed",
+           "subtype": "add",
+           "name": "faked_new_emoji",
+           "value": "<img-url>"
+         }
+       }' https://<django-project-domain>/emojiwatch/event_hook
+
+   Assuming everything's been set up correctly so far, this should result in a post to your Slack channel (``C8VSYSEQ22``):
+
+   .. image:: img/slack_event_message.png
+      :alt: An Emojiwatch post to Slack
 
 Requirements
 ------------

diff --git a/tests/django_settings.py b/tests/django_settings.py
@@ -24,6 +24,7 @@
 # ---- Imports -----------------------------------------------------------
 
 import logging
+import os
 
 # ---- Data --------------------------------------------------------------
 
@@ -45,8 +46,8 @@
 DEBUG = True
 
 EMOJIWATCH = {
-    'slack_auth_token': 'xoxa-for-testing-only-not-a-real-auth-token',
-    'slack_verification_token': 'FoRtEsTiNgOnLyNoTaReAlVeRiFiCaTiOnToKeN',
+    'slack_auth_token': os.environ.get('EMOJIWATCH_SLACK_AUTH_TOKEN', 'xoxa-for-testing-only-not-a-real-auth-token'),
+    'slack_verification_token': os.environ.get('EMOJIWATCH_SLACK_VERIFICATION_TOKEN', 'FoRtEsTiNgOnLyNoTaReAlVeRiFiCaTiOnToKeN'),
 }
 
 INSTALLED_APPS = (