Update docs v2 #427
Update docs v2 #427
Conversation
|
|
Codecov Report
@@ Coverage Diff @@
## update_docs_v2 #427 +/- ##
===============================================
Coverage 56.96% 56.96%
===============================================
Files 6 6
Lines 732 732
Branches 42 42
===============================================
Hits 417 417
Misses 306 306
Partials 9 9Continue to review full report at Codecov.
|
There was a problem hiding this comment.
Thanks for this update @jimray! I've added a few comments inline. I also have a couple questions:
- Should we keep the v2 docs around for a few weeks so that people who are using those links aren't left with a 404?
- I'd like to move to markdown files instead of RestructuredText. Should we do that now or in a subsequent PR?
| As mentioned above, we're setting the app tokens and other configs in environment variables and pulling them into global variables. | ||
|
|
||
| Depending on what actions your app will need to perform, you'll need different OAuth permission scopes. Review the available scopes `here <https://api.slack.com/docs/oauth-scopes>`_. | ||
| To configure your app for OAuth, you'll need a client ID, a client secret, and a set of one or more scopes that will be applied to the token once it is granted. The client ID and client secret are available from your `app's configuration page <https://api.slack.com/apps>`_. The scopes are determined by the functionality of the app -- every method you wish to access has a corresponding scope and your app will need to request that scope in order to be able to access the method. Review Slack's `full list of OAuth scopes <https://api.slack.com/docs/oauth-scopes>`_. | ||
|
|
||
| .. code-block:: python | ||
|
|
There was a problem hiding this comment.
The import statement here needs to be updated.
docs-src/auth.rst
Outdated
|
|
||
| Once your user has completed the OAuth flow, you'll be able to use the provided | ||
| tokens to make a variety of Web API calls on behalf of the user and your app's bot user. | ||
| Once your user has completed the OAuth flow, you'll be able to use the provided tokens to call any of Slack's API methods that require an access token. | ||
|
|
||
| See the :ref:`Web API usage <web-api-examples>` section of this documentation for usage examples. |
There was a problem hiding this comment.
This link appears to be broken.
docs-src/basic_usage.rst
Outdated
| import time | ||
|
|
||
| slack_token = os.environ["SLACK_API_TOKEN"] | ||
| sc = SlackClient(slack_token) | ||
| client = slack.WebClient(slack_token) |
There was a problem hiding this comment.
We should update this and few other places to use keyword-arguments. Replace client = slack.WebClient(slack_token) with client = slack.WebClient(token=slack_token).
| ****************** | ||
|
|
||
| Well, poop. Take a deep breath, and then let us know on the `Issue Tracker`_. If you're feeling particularly ambitious, | ||
| why not submit a `pull request`_ with a bug fix? | ||
| That's great! Thank you. Let us know on the `Issue Tracker`_. If you're feeling particularly ambitious, why not submit a `pull request`_ with a bug fix? |
There was a problem hiding this comment.
These links appear to be broken.
docs-src/faq.rst
Outdated
|
|
||
| All done? Great! While we're super excited to incorporate your new feature into |product_name|, there are a | ||
| couple of things we want to make sure you've given thought to. | ||
| All done? Great! While we're super excited to incorporate your new feature into |product_name|, there are a couple of things we want to make sure you've given thought to. |
There was a problem hiding this comment.
I have no idea what product_name is supposed to be. Should we remove this?
I'm of the opinions that we can nuke these from the main repo since they'll still exist in the repo history
Definitely agree, let's save that for a subsequent PR. I suspect this will requires some more extensive testing with PyPi and RTD |
Summary
I updated the docs to be compatible with v2 of the SDK. Almost all of the prose has been edited, updated, or entirely rewritten. Headlines clarified and navigation should be easier to follow. All of the sample code is updated for Py3 and v2 of our SDK.
I wasn't able to update the RTM docs yet.
Requirements (place an
xin each[ ])