Docs: reorganizes nav to match Bolt JS style (#1241)

Author: lukegalbraithrussell

docs/README.md

@@ -71,7 +71,6 @@ Then grab the latest version of Node.
 nvm install node
 ```
 
-
 If you are running this project locally for the first time, you'll need to install the packages with the following command:
 
 ```

docs/content/basic/action-listening.md

@@ -0,0 +1,73 @@
+---
+title: Listening & responding to actions
+lang: en
+slug: /concepts/actions
+---
+
+Your app can listen and respond to user actions, like button clicks, and menu selects, using the `action` method.
+
+## Listening to actions
+
+Actions can be filtered on an `action_id` parameter of type `str` or `re.Pattern`. The `action_id` parameter acts as a unique identifier for interactive components on the Slack platform.
+
+You'll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the request was received from Slack. This is discussed in the [acknowledging requests guide](/concepts/acknowledge).
+
+Refer to [the module document](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html) to learn the available listener arguments.
+
+```python
+# Your listener will be called every time a block element with the action_id "approve_button" is triggered
+@app.action("approve_button")
+def update_message(ack):
+    ack()
+    # Update the message to reflect the action
+```
+
+### Listening to actions using a constraint object
+
+You can use a constraints object to listen to `block_id`s and `action_id`s (or any combination of them). Constraints in the object can be of type `str` or `re.Pattern`.
+
+```python
+# Your function will only be called when the action_id matches 'select_user' AND the block_id matches 'assign_ticket'
+@app.action({
+    "block_id": "assign_ticket",
+    "action_id": "select_user"
+})
+def update_message(ack, body, client):
+    ack()
+
+    if "container" in body and "message_ts" in body["container"]:
+        client.reactions_add(
+            name="white_check_mark",
+            channel=body["channel"]["id"],
+            timestamp=body["container"]["message_ts"],
+        )
+```
+
+## Responding to actions
+
+There are two main ways to respond to actions. The first (and most common) way is to use `say()`, which sends a message back to the conversation where the incoming request took place.
+
+The second way to respond to actions is using `respond()`, which is a utility to use the `response_url` associated with the action.
+
+Refer to [the module document](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html) to learn the available listener arguments.
+
+```python
+# Your listener will be called every time an interactive component with the action_id “approve_button” is triggered
+@app.action("approve_button")
+def approve_request(ack, say):
+    # Acknowledge action request
+    ack()
+    say("Request approved 👍")
+```
+
+### Using `respond()` method
+
+Since `respond()` is a utility for calling the `response_url`, it behaves in the same way. You can pass [all the message payload properties](https://api.slack.com/reference/messaging/payload) as keyword arguments along with optional properties like `response_type` (which has a value of `"in_channel"` or `"ephemeral"`), `replace_original`, `delete_original`, `unfurl_links`, and `unfurl_media`. With that, your app can send a new message payload that will be published back to the source of the original interaction.
+
+```python
+# Listens to actions triggered with action_id of “user_select”
+@app.action("user_select")
+def select_user(ack, action, respond):
+    ack()
+    respond(f"You selected <@{action['selected_user']}>")
+```

docs/content/basic/action-respond.md

@@ -4,15 +4,13 @@ lang: en
 slug: /concepts/adapters
 ---
 
+Adapters are responsible for handling and parsing incoming requests from Slack to conform to [`BoltRequest`](https://github.com/slackapi/bolt-python/blob/main/slack_bolt/request/request.py), then dispatching those requests to your Bolt app.
 
-Adapters are responsible for handling and parsing incoming requests from Slack to conform to <a href="https://github.com/slackapi/bolt-python/blob/main/slack_bolt/request/request.py">`BoltRequest`</a>, then dispatching those requests to your Bolt app.
-
-By default, Bolt will use the built-in <a href="https://docs.python.org/3/library/http.server.html">`HTTPServer`</a> adapter. While this is okay for local development, <b>it is not recommended for production</b>. Bolt for Python includes a collection of built-in adapters that can be imported and used with your app. The built-in adapters support a variety of popular Python frameworks including Flask, Django, and Starlette among others. Adapters support the use of any production-ready web server of your choice.
+By default, Bolt will use the built-in [`HTTPServer`](https://docs.python.org/3/library/http.server.html) adapter. While this is okay for local development, **it is not recommended for production**. Bolt for Python includes a collection of built-in adapters that can be imported and used with your app. The built-in adapters support a variety of popular Python frameworks including Flask, Django, and Starlette among others. Adapters support the use of any production-ready web server of your choice.
 
 To use an adapter, you'll create an app with the framework of your choosing and import its corresponding adapter. Then you'll initialize the adapter instance and call its function that handles and parses incoming requests.
 
-The full list adapters, as well as configuration and sample usage, can be found within the repository's <a href="https://github.com/slackapi/bolt-python/tree/main/examples">`examples` folder</a>.
-
+The full list adapters, as well as configuration and sample usage, can be found within the repository's [`examples`](https://github.com/slackapi/bolt-python/tree/main/examples)
 
 ```python
 from slack_bolt import App

docs/content/basic/acknowledge.md docs/content/concepts/acknowledge.mddocs/content/basic/acknowledge.md renamed to docs/content/concepts/acknowledge.md

@@ -4,9 +4,9 @@ lang: en
 slug: /concepts/app-home
 ---
 
-<a href="https://api.slack.com/surfaces/tabs/using">Home tabs</a> are customizable surfaces accessible via the sidebar and search that allow apps to display views on a per-user basis. After enabling App Home within your app configuration, home tabs can be published and updated by passing a `user_id` and <a href="https://api.slack.com/reference/block-kit/views">view payload</a> to the <a href="https://api.slack.com/methods/views.publish">`views.publish`</a> method.
+[Home tabs](https://api.slack.com/surfaces/tabs/using) are customizable surfaces accessible via the sidebar and search that allow apps to display views on a per-user basis. After enabling App Home within your app configuration, home tabs can be published and updated by passing a `user_id` and [view payload](https://api.slack.com/reference/block-kit/views) to the [`views.publish`](https://api.slack.com/methods/views.publish) method.
 
-You can subscribe to the <a href="https://api.slack.com/events/app_home_opened">`app_home_opened`</a> event to listen for when users open your App Home.
+You can subscribe to the [`app_home_opened`](https://api.slack.com/events/app_home_opened) event to listen for when users open your App Home.
 
 Refer to [the module document](https://tools.slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html) to learn the available listener arguments.
 ```python

docs/content/concepts/actions.md

@@ -277,7 +277,6 @@ def respond_to_user_messages(logger: logging.Logger, set_status: SetStatus, say:
         logger.exception(f"Failed to respond to an inquiry: {e}")
         say(f":warning: Sorry, something went wrong during processing your request (error: {e})")
 
-
 # Enable this assistant middleware in your Bolt app
 app.use(assistant)
 ```

docs/content/advanced/adapters.md docs/content/concepts/adapters.mddocs/content/advanced/adapters.md renamed to docs/content/concepts/adapters.md

@@ -4,11 +4,9 @@ lang: en
 slug: /concepts/async
 ---
 
+To use the async version of Bolt, you can import and initialize an `AsyncApp` instance (rather than `App`). `AsyncApp` relies on [AIOHTTP](https://docs.aiohttp.org) to make API requests, which means you'll need to install `aiohttp` (by adding to `requirements.txt` or running `pip install aiohttp`).
 
-To use the async version of Bolt, you can import and initialize an `AsyncApp` instance (rather than `App`). `AsyncApp` relies on <a href="https://docs.aiohttp.org/">AIOHTTP</a> to make API requests, which means you'll need to install `aiohttp` (by adding to `requirements.txt` or running `pip install aiohttp`).
-
-Sample async projects can be found within the repository's <a href="https://github.com/slackapi/bolt-python/tree/main/examples">`examples` folder</a>.
-
+Sample async projects can be found within the repository's [examples](https://github.com/slackapi/bolt-python/tree/main/examples) folder.
 
 ```python
 # Requirement: install aiohttp
@@ -28,12 +26,7 @@ if __name__ == "__main__":
     app.start(3000)
 ```
 
-<details>
-<summary>
-Using other frameworks
-</summary>
-
-
+## Using other frameworks
 
 Internally `AsyncApp#start()` implements a [`AIOHTTP`](https://docs.aiohttp.org/) web server. If you prefer, you can use a framework other than `AIOHTTP` to handle incoming requests.
 
@@ -48,7 +41,6 @@ pip install slack_bolt sanic uvicorn
 uvicorn async_app:api --reload --port 3000 --log-level debug
 ```
 
-
 ```python
 from slack_bolt.async_app import AsyncApp
 app = AsyncApp()
@@ -76,5 +68,4 @@ async def endpoint(req: Request):
 
 if __name__ == "__main__":
     api.run(host="0.0.0.0", port=int(os.environ.get("PORT", 3000)))
-```
-</details>
+```

docs/content/basic/app-home.md docs/content/concepts/app-home.mddocs/content/basic/app-home.md renamed to docs/content/concepts/app-home.md

@@ -35,10 +35,7 @@ app = App(
 )
 ```
 
-<details>
-<summary>
-Customizing OAuth defaults
-</summary>
+## Customizing OAuth defaults
 
 You can override the default OAuth using `oauth_settings`, which can be passed in during the initialization of App. You can override the following:
 
@@ -90,6 +87,4 @@ app = App(
         callback_options=callback_options,
     ),
 )
-```
-
-</details>
+```