Docs: adds Docusaurus site (#1537)

.github/dependabot.yml

@@ -12,3 +12,7 @@ updates:
     directory: "/"
     schedule:
       interval: "monthly"
+  - package-ecosystem: "npm"
+    directory: "/docs"
+    schedule:
+      interval: "monthly"

.github/maintainers_guide.md

@@ -107,17 +107,9 @@ $ ./scripts/run_integration_tests.sh integration_tests/web/test_async_web_client
 
 ### Generating Documentation
 
-The documentation is generated from the source and templates in the `docs-src` directory. The generated documentation
-gets committed to the repo in `docs` and also published to a GitHub Pages website.
+See [`/docs/README`](https://github.com/slackapi/python-slack-sdk/blob/main/docs/README.md) for information on editing documentation pages.
 
-You can generate and preview the **SDK document pages** by running
-
-```bash
-$ ./scripts/docs.sh
-$ open docs/index.html
-```
-
-Similarly you can generate and preview the **API documents for `slack_sdk` package modules** by running
+The API reference is generated from a script. You can generate and preview the **API _reference_ documents for `slack_sdk` package modules** by running:
 
 ```bash
 $ ./scripts/generate_api_docs.sh
@@ -128,7 +120,7 @@ $ ./scripts/generate_api_docs.sh
 1. Create the commit for the release:
 
    - Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `slack_sdk/version.py`.
-   - Build the docs with `./scripts/docs.sh` and then `./scripts/generate_api_docs.sh`.
+   - Build the reference docs with `./scripts/generate_api_docs.sh`.
    - Create a branch for the release with `git checkout -b v2.5.0`
    - Make a commit that includes the new version number: `git commit -a -m 'version 2.5.0'`.
    - Open a PR and merge after receiving at least one approval from other maintainers.

.github/pull_request_template.md

@@ -17,7 +17,7 @@
 - [ ] **slack_sdk.scim** (SCIM API client)
 - [ ] **slack_sdk.audit_logs** (Audit Logs API client)
 - [ ] **slack_sdk.rtm_v2** (RTM client)
-- [ ] `/docs-src` (Documents, have you run `./scripts/docs.sh`?)
+- [ ] `/docs-src` (Documents)
 - [ ] `/tutorial` (PythOnBoardingBot tutorial)
 - [ ] `tests`/`integration_tests` (Automated tests for this library)
 

.github/workflows/docs-deploy.yml

@@ -0,0 +1,63 @@
+name: Deploy to GitHub Pages
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+  workflow_dispatch:
+  release:
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: ./docs
+
+      - name: Build website
+        run: npm run build
+        working-directory: ./docs
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name != 'pull_request'
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # verifies deployment is from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,10 +1,6 @@
 # general things to ignore
 build/
 dist/
-docs/_sources/
-docs/.doctrees
-docs-v2/_sources/
-docs-v2/.doctrees
 .eggs/
 *.egg-info/
 *.egg

README.md

@@ -90,7 +90,7 @@ $ pip install slack_sdk
 
 ---
 
-We've created this [tutorial](https://github.com/slackapi/python-slack-sdk/tree/main/tutorial) to build a basic Slack app in less than 10 minutes. It requires some general programming knowledge, and Python basics. It focuses on the interacting with Slack's Web and RTM API. Use it to give you an idea of how to use this SDK.
+We've created this [tutorial](https://github.com/slackapi/python-slack-sdk/tree/main/tutorial) to build a basic Slack app in less than 10 minutes. It requires some general programming knowledge, and Python basics. It focuses on the interacting with the Slack Web API and RTM API. Use it to give you an idea of how to use this SDK.
 
 **[Read the tutorial to get started!](https://github.com/slackapi/python-slack-sdk/tree/main/tutorial)**