Add v3.3 documents #939 by seratch · Pull Request #943 · slackapi/python-slack-sdk

seratch · 2021-02-04T04:25:16Z

Summary

This pull request fixes #939

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

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

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 python setup.py validate after making the changes.

codecov · 2021-02-04T04:29:43Z

Codecov Report

Merging #943 (1683017) into main (017dff9) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #943   +/-   ##
=======================================
  Coverage   85.32%   85.32%           
=======================================
  Files          67       67           
  Lines        5902     5902           
=======================================
  Hits         5036     5036           
  Misses        866      866

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 017dff9...7caaf02. Read the comment docs.

docs-src/scim/index.rst

docs-src/audit-logs/index.rst

misscoded · 2021-02-04T04:44:52Z

docs-src/audit-logs/index.rst

+
+An OAuth token with `the admin scope <https://api.slack.com/scopes/admin>`_ is required to access this API.
+
+Probably, you are going to use the ``/logs`` endpoint. To learn available parameters for the endpoint, check `the guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. Also, you can check the data structure of ``api_response.typed_body`` `here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.


Suggested change

Probably, you are going to use the ``/logs`` endpoint. To learn available parameters for the endpoint, check `the guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. Also, you can check the data structure of ``api_response.typed_body`` `here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.

You will likely use the ``/logs`` endpoint to ???.

To learn about the available parameters for this endpoint, check out `this guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. You can also learn more about the data structure of ``api_response.typed_body`` `here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.

The ??? should be replaced with a concise why, IMO. It's not clear to me as a reader why I'd be using /logs and this is a good place to underscore its purpose.

Thanks. I don't think we need to mention detailed reasons here. Audit Logs API users should already know what it is. Also, I would like to avoid repeating duplicated topics with the API document.

misscoded · 2021-02-04T04:46:44Z

docs-src/index.rst

-| RTM API                        | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | ``slack_sdk.rtm```                 |
+| Audit Logs API                 | Receive audit logs API data.                                                                  | ``slack_sdk.audit_logs``           |
+--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
+| SCIM API                       | Utilize the SCIM APIs for provisioning and managing user accounts and groups                  | ``slack_sdk.scim``                 |


Will modify manually later (rst requires consistent indent in a table)

docs-src/real_time_messaging.rst

docs-src/scim/index.rst

seratch

Thanks a lot for your review @misscoded !

seratch · 2021-02-04T05:10:17Z

docs-src/audit-logs/index.rst

+
+An OAuth token with `the admin scope <https://api.slack.com/scopes/admin>`_ is required to access this API.
+
+Probably, you are going to use the ``/logs`` endpoint. To learn available parameters for the endpoint, check `the guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. Also, you can check the data structure of ``api_response.typed_body`` `here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.


Thanks. I don't think we need to mention detailed reasons here. Audit Logs API users should already know what it is. Also, I would like to avoid repeating duplicated topics with the API document.

seratch · 2021-02-04T05:11:07Z

docs-src/index.rst

-| RTM API                        | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | ``slack_sdk.rtm```                 |
+| Audit Logs API                 | Receive audit logs API data.                                                                  | ``slack_sdk.audit_logs``           |
+--------------------------------+-----------------------------------------------------------------------------------------------+------------------------------------+
+| SCIM API                       | Utilize the SCIM APIs for provisioning and managing user accounts and groups                  | ``slack_sdk.scim``                 |


Will modify manually later (rst requires consistent indent in a table)

docs-src/scim/index.rst

Co-authored-by: Alissa Renz <alissa.renz@gmail.com>

mwbrooks

👌

docs-src/audit-logs/index.rst

mwbrooks · 2021-02-04T19:37:18Z

docs-src/real_time_messaging.rst


 **Connecting to the RTM API**

+Note that the import here is not ``from slack_sdk.rtm import RTMClient`` but ``from slack_sdk.rtm.v2 import RTMClient`` (``v2`` is added in the latter one). If you would like to use the legacy version of the client, go to the next section.


Very helpful comment to add to the docs!

Co-authored-by: Michael Brooks <michael@michaelbrooks.ca>

seratch added docs M-T: Documentation work only Version: 3x labels Feb 4, 2021

seratch added this to the 3.3.0 milestone Feb 4, 2021

seratch requested review from misscoded, mwbrooks and stevengill February 4, 2021 04:25

seratch self-assigned this Feb 4, 2021

misscoded approved these changes Feb 4, 2021

View reviewed changes

seratch commented Feb 4, 2021

View reviewed changes

stevengill approved these changes Feb 4, 2021

View reviewed changes

seratch and others added 6 commits February 4, 2021 14:59

Add v3.3 documents slackapi#939

2e7f242

Apply suggestions from code review

235a2c9

Co-authored-by: Alissa Renz <alissa.renz@gmail.com>

Update GitHub templates

22572ae

Apply more suggestions by Alissa

70415f7

Run ./docs.sh

5923a4b

Update docs-src/scim/index.rst

fb73c37

Co-authored-by: Alissa Renz <alissa.renz@gmail.com>

seratch force-pushed the issue-939-3.3-docs branch from 1683017 to fb73c37 Compare February 4, 2021 06:00

mwbrooks approved these changes Feb 4, 2021

View reviewed changes

Apply suggestions from code review

7caaf02

Co-authored-by: Michael Brooks <michael@michaelbrooks.ca>

seratch merged commit a52701f into slackapi:main Feb 5, 2021

seratch deleted the issue-939-3.3-docs branch February 5, 2021 02:09


		An OAuth token with `the admin scope <https://api.slack.com/scopes/admin>`_ is required to access this API.

		Probably, you are going to use the ``/logs`` endpoint. To learn available parameters for the endpoint, check `the guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. Also, you can check the data structure of ``api_response.typed_body`` `here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.

-Probably, you are going to use the ``/logs`` endpoint. To learn available parameters for the endpoint, check `the guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. Also, you can check the data structure of ``api_response.typed_body`` `here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.
+You will likely use the ``/logs`` endpoint to ???.
+To learn about the available parameters for this endpoint, check out `this guide <https://api.slack.com/admins/audit-logs#how_to_call_the_audit_logs_api>`_. You can also learn more about the data structure of ``api_response.typed_body`` `here <https://github.com/slackapi/python-slack-sdk/blob/main/slack_sdk/audit_logs/v1/logs.py>`_.

	\| SCIM API \| Utilize the SCIM APIs for provisioning and managing user accounts and groups \| ``slack_sdk.scim`` \|
	\| SCIM API \| Utilize the SCIM APIs for provisioning and managing user accounts and groups. \| ``slack_sdk.scim`` \|


		Connecting to the RTM API

		Note that the import here is not ``from slack_sdk.rtm import RTMClient`` but ``from slack_sdk.rtm.v2 import RTMClient`` (``v2`` is added in the latter one). If you would like to use the legacy version of the client, go to the next section.

Conversation

seratch commented Feb 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

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

Requirements (place an x in each [ ])

Uh oh!

codecov bot commented Feb 4, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

misscoded Feb 4, 2021

Choose a reason for hiding this comment

Uh oh!

seratch Feb 4, 2021

Choose a reason for hiding this comment

Uh oh!

misscoded Feb 4, 2021

Choose a reason for hiding this comment

Uh oh!

seratch Feb 4, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

seratch left a comment

Choose a reason for hiding this comment

Uh oh!

seratch Feb 4, 2021

Choose a reason for hiding this comment

Uh oh!

seratch Feb 4, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mwbrooks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mwbrooks Feb 4, 2021

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

seratch commented Feb 4, 2021 •

edited

Loading

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

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

codecov bot commented Feb 4, 2021 •

edited

Loading