Add Basic Concepts section to docs #78

misscoded · 2020-09-11T23:33:21Z

Basic Concepts section of Bolt for Python documentation (based on Bolt for JavaScript: Basic Concepts).

Preview for Review + Readability: https://misscoded.github.io/bolt-python/concepts

Part of Issue #70 (Add Getting Started Guide)

Category (place an `x` in each of the `[ ]`)

slack_bolt.App and/or its core components
slack_bolt.async_app.AsyncApp and/or its core components
Adapters in slack_bolt.adapter
Documentation

Requirements (place an `x` in each `[ ]`)

Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you are agreeing to those rules.

I've read and understood the Contributing Guidelines and have done my best effort to follow them.
I've read and agree to the Code of Conduct.
I've run ./scripts/run_tests.sh after making the changes.

docs/_basic/authenticating_oauth.md

codecov-commenter · 2020-09-11T23:44:03Z

Codecov Report

❗ No coverage uploaded for pull request base (docs@45d4852). Click here to learn what that means.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             docs      #78   +/-   ##
=======================================
  Coverage        ?   82.57%           
=======================================
  Files           ?      128           
  Lines           ?     3530           
  Branches        ?        0           
=======================================
  Hits            ?     2915           
  Misses          ?      615           
  Partials        ?        0

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 45d4852...631b046. Read the comment docs.

docs/_basic/acknowledging_events.md

docs/_basic/authenticating_oauth.md

docs/_basic/sending_messages.md

docs/_basic/updating_pushing_modals.md

docs/_basic/web_api.md

seratch · 2020-09-12T00:48:53Z

docs/_basic/web_api.md

+def say_hello(client, payload):
+    # Unix Epoch time for September 30, 2020 11:59:59 PM
+    when_september_ends = 1601510399
+    channel_id = payload['event']['channel']
+    client.chat_scheduleMessage(channel=channel_id,
+                                post_at=when_september_ends,
+                                text="Summer has come and passed")


Suggested change

def say_hello(client, payload):

# Unix Epoch time for September 30, 2020 11:59:59 PM

when_september_ends = 1601510399

channel_id = payload['event']['channel']

client.chat_scheduleMessage(channel=channel_id,

post_at=when_september_ends,

text="Summer has come and passed")

def say_hello(client, message):

# Unix Epoch time for September 30, 2020 11:59:59 PM

when_september_ends = 1601510399

channel_id = message['channel']

client.chat_scheduleMessage(channel=channel_id,

post_at=when_september_ends,

text="Summer has come and passed")

TODO: channel: message.channel.id in Bolt JS is incorrect.

seratch · 2020-09-12T00:50:14Z

I've mainly taken a look at code snippets but I haven't verified many of them actually work yet.

docs/_basic/web_api.md

seratch · 2020-09-12T01:18:23Z

Some of my comments above include TODOs in Bolt for JS documents. If anyone can take the tasks, it'd be appreciated.

docs/_basic/acknowledging_events.md

docs/_basic/authenticating_oauth.md

shaydewael · 2020-09-14T21:55:19Z

docs/_basic/authenticating_oauth.md

+
+Bolt for Python will create a **Redirect URL** `slack/oauth_redirect`, which Slack uses to redirect users after they complete your app’s installation flow. You will need to add this **Redirect URL** in your app configuration settings under **OAuth and Permissions**. This path can be configured in the `OAuthSettings` argument described below.
+
+Bolt for Python will also create a `slack/install` route, where you can find an **Add to Slack** button for your app to perform direct installs of your app. If you need any additional authorizations (user tokens) from users inside a team when your app is already installed or a reason to dynamically generate an install URL, you can pass your own custom URL generator to `oauth_settings` as `authorize_url_generator`.


Similar to Bolt for JS, I think it'd be helpful to link to OAuth docs when discussing authorize_url_generator if there are more detailed docs on that piece.

The same OAuth docs linked above, I assume? BoltJS's docs link to a specific anchor, but as this page doesn't exist yet, I'm not sure what this link will be.

I will take this!

docs/_basic/listening_actions.md

docs/_basic/listening_events.md

docs/_basic/opening_modals.md

docs/_basic/responding_actions.md

docs/_basic/updating_pushing_modals.md

docs/_basic/web_api.md

docs/_basic/acknowledging_events.md

misscoded · 2020-09-16T03:41:10Z

docs/_basic/listening_modals.md

+def handle_submission(ack, body, client, view):
+    # Acknowledge the view_submission event
+    ack()
+


@seratch I've managed to lose the validation request you placed here. Could you possibly provide a snippet of what you had in mind so I can fold it in?

@misscoded How about having simpler ones such as length-check? Here is an example I recently created: https://github.com/seratch/apidays-workshop-2020/blob/87f623356f90fbdb9f5112e114dc51c157698ac7/python/app.py#L272-L283

ref slackapi/bolt-python#78 (comment)

seratch · 2020-09-16T08:32:00Z

Some of my comments above include TODOs in Bolt for JS documents. If anyone can take the tasks, it'd be appreciated.

I sent a PR: slackapi/bolt-js#628

seratch · 2020-09-16T21:28:45Z

docs/_basic/listening_events.md

+
+```python
+# Matches all messages from bot users
+@app.message({"subtype": "message_changed"})


@misscoded This code doesn't work even with Bolt for JS. Use another example. app.event? #89

seratch · 2020-09-16T21:33:19Z

docs/_basic/listening_modals.md

+def handle_submission(ack, body, client, view):
+    # Acknowledge the view_submission event
+    ack()
+


@misscoded How about having simpler ones such as length-check? Here is an example I recently created: https://github.com/seratch/apidays-workshop-2020/blob/87f623356f90fbdb9f5112e114dc51c157698ac7/python/app.py#L272-L283

seratch · 2020-09-16T21:34:11Z

docs/_basic/authenticating_oauth.md

+</div>
+
+```python
+from slack_bolt.oauth.oauth_settings import OAuthSettings


@misscoded Just in case

Suggested change

from slack_bolt.oauth.oauth_settings import OAuthSettings

import os

from slack_bolt.oauth.oauth_settings import OAuthSettings

seratch · 2020-09-16T21:36:36Z

docs/_basic/authenticating_oauth.md

+        install_path="/slack/install",
+        redirect_uri_path="/slack/oauth_redirect",
+        state_store=FileOAuthStateStore(expiration_seconds=600),
+        callback_options=CallbackOptions(success=success,


@misscoded we should have samples for success / failure functions like this:

bolt-python/tests/slack_bolt/oauth/test_oauth_flow.py

Lines 141 to 148 in c1641f8

def success(args: SuccessArgs) -> BoltResponse:

assert args.request is not None

return BoltResponse(status=200, body="customized")

def failure(args: FailureArgs) -> BoltResponse:

assert args.request is not None

assert args.reason is not None

return BoltResponse(status=502, body="customized")

You don't need to have the type hints in docs.

seratch · 2020-09-18T01:50:27Z

The App Home page has been added in JS: slackapi/bolt-js#626

seratch · 2020-09-18T22:46:43Z

hmm, I'm unable to reopen this. @misscoded Could you reopen or create a new PR?

seratch · 2020-09-18T22:53:21Z

I found that the reason was the deletion of the docs branch. I restored the branch and reopened this.

@misscoded We no longer use docs branch. Can you change the base branch or create a new PR to main branch?

seratch · 2020-09-19T00:22:04Z

We're going to merge #94 - thanks @misscoded for your great work here!

first pass at basic concepts section of docs

168ba0c

misscoded added the docs Improvements or additions to documentation label Sep 11, 2020

misscoded requested review from seratch, mwbrooks and shaydewael September 11, 2020 23:33

misscoded self-assigned this Sep 11, 2020

misscoded changed the base branch from main to docs September 11, 2020 23:37

misscoded commented Sep 11, 2020

View reviewed changes

docs/_basic/authenticating_oauth.md Show resolved Hide resolved

misscoded added this to the 0.9.0b0 milestone Sep 11, 2020

misscoded linked an issue Sep 11, 2020 that may be closed by this pull request

Add Getting Started guide #70

Closed

seratch requested changes Sep 12, 2020

View reviewed changes

seratch reviewed Sep 12, 2020

View reviewed changes

docs/_basic/web_api.md Outdated Show resolved Hide resolved

This was referenced Sep 12, 2020

app.action without type should work for more actions #80

Closed

Add more tests and samples for dialogs #81

Closed

update docs > basics with kaz feedback

7dce923

shaydewael suggested changes Sep 14, 2020

View reviewed changes

update docs > basics with shay feedback

cc11ab8

shaydewael reviewed Sep 16, 2020

View reviewed changes

docs/_basic/acknowledging_events.md Outdated Show resolved Hide resolved

shaydewael approved these changes Sep 16, 2020

View reviewed changes

misscoded commented Sep 16, 2020

View reviewed changes

seratch mentioned this pull request Sep 16, 2020

Make sure if @app.message({"subtype": "message_changed"}) works #89

Closed

2 tasks

seratch added a commit to seratch/bolt-js that referenced this pull request Sep 16, 2020

Fix a code snippet that doesn't work

014f9f8

ref slackapi/bolt-python#78 (comment)

seratch added a commit to seratch/bolt-js that referenced this pull request Sep 16, 2020

Add hash parameter to views.update API calls

480f0cb

ref slackapi/bolt-python#78 (comment)

seratch added a commit to seratch/bolt-js that referenced this pull request Sep 16, 2020

Fix a code snippet that doesn't work

cd209e8

ref slackapi/bolt-python#78 (comment)

seratch mentioned this pull request Sep 16, 2020

Fix code snippet errors in docs slackapi/bolt-js#628

Merged

2 tasks

minor text change + remove dialog submission ref/example

631b046

seratch requested changes Sep 16, 2020

View reviewed changes

seratch closed this Sep 18, 2020

seratch reopened this Sep 18, 2020

seratch mentioned this pull request Sep 19, 2020

Merge #78 with a few adjustments #94

Merged

3 tasks

seratch closed this Sep 19, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Basic Concepts section to docs #78

Add Basic Concepts section to docs #78

misscoded commented Sep 11, 2020 •

edited

Loading

codecov-commenter commented Sep 11, 2020 •

edited

Loading

seratch Sep 12, 2020

seratch Sep 12, 2020

seratch commented Sep 12, 2020

seratch commented Sep 12, 2020

shaydewael Sep 14, 2020

misscoded Sep 15, 2020

seratch Sep 15, 2020

misscoded Sep 16, 2020

seratch Sep 16, 2020

seratch commented Sep 16, 2020

seratch Sep 16, 2020

seratch Sep 16, 2020

seratch Sep 16, 2020

seratch Sep 16, 2020

seratch commented Sep 18, 2020

seratch commented Sep 18, 2020

seratch commented Sep 18, 2020

seratch commented Sep 19, 2020


		Bolt for Python will create a Redirect URL `slack/oauth_redirect`, which Slack uses to redirect users after they complete your app’s installation flow. You will need to add this Redirect URL in your app configuration settings under OAuth and Permissions. This path can be configured in the `OAuthSettings` argument described below.

		Bolt for Python will also create a `slack/install` route, where you can find an Add to Slack button for your app to perform direct installs of your app. If you need any additional authorizations (user tokens) from users inside a team when your app is already installed or a reason to dynamically generate an install URL, you can pass your own custom URL generator to `oauth_settings` as `authorize_url_generator`.

	from slack_bolt.oauth.oauth_settings import OAuthSettings
	import os
	from slack_bolt.oauth.oauth_settings import OAuthSettings

	def success(args: SuccessArgs) -> BoltResponse:
	assert args.request is not None
	return BoltResponse(status=200, body="customized")

	def failure(args: FailureArgs) -> BoltResponse:
	assert args.request is not None
	assert args.reason is not None
	return BoltResponse(status=502, body="customized")

Add Basic Concepts section to docs #78

Add Basic Concepts section to docs #78

Conversation

misscoded commented Sep 11, 2020 • edited Loading

Preview for Review + Readability: https://misscoded.github.io/bolt-python/concepts

Category (place an x in each of the [ ])

Requirements (place an x in each [ ])

codecov-commenter commented Sep 11, 2020 • edited Loading

Codecov Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seratch commented Sep 12, 2020

seratch commented Sep 12, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seratch commented Sep 16, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

seratch commented Sep 18, 2020

seratch commented Sep 18, 2020

seratch commented Sep 18, 2020

seratch commented Sep 19, 2020

misscoded commented Sep 11, 2020 •

edited

Loading

Category (place an `x` in each of the `[ ]`)

Requirements (place an `x` in each `[ ]`)

codecov-commenter commented Sep 11, 2020 •

edited

Loading