Docs: creates markdown reference

.github/workflows/ci-build.yml

@@ -58,6 +58,27 @@ jobs:
       - name: Type check all modules
         run: mypy --config-file pyproject.toml
 
+  docs-reference:
+    name: Reference docs drift
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python ${{ env.LATEST_SUPPORTED_PY }}
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ env.LATEST_SUPPORTED_PY }}
+      # Regenerating also runs the MDX/acorn hazard gate inside the generator,
+      # so a stale tree or an unfenced code example both fail here.
+      - name: Regenerate the API reference
+        run: ./scripts/generate_api_docs.sh
+      - name: Fail if the committed reference is out of date
+        run: git diff --exit-code -- docs/english/reference
+
   unittest:
     name: Unit tests
     runs-on: ubuntu-22.04

docs/english/_sidebar.json

@@ -6,15 +6,18 @@
 		"className": "sidebar-title"
 	},
 	"tools/bolt-python/getting-started",
-	{ "type": "html", "value": "<hr>" },
+	{
+		"type": "html",
+		"value": "<hr>"
+	},
 	"tools/bolt-python/creating-an-app",
 	{
 		"type": "category",
 		"label": "AI & Agents",
 		"link": {
 			"type": "doc",
 			"id": "tools/bolt-python/concepts/adding-agent-features"
-		  },
+		},
 		"items": [
 			"tools/bolt-python/concepts/adding-agent-features",
 			"tools/bolt-python/concepts/using-the-assistant-class"
@@ -100,9 +103,14 @@
 	{
 		"type": "category",
 		"label": "Legacy",
-		"items": ["tools/bolt-python/legacy/steps-from-apps"]
+		"items": [
+			"tools/bolt-python/legacy/steps-from-apps"
+		]
+	},
+	{
+		"type": "html",
+		"value": "<hr>"
 	},
-	{ "type": "html", "value": "<hr>" },
 	{
 		"type": "category",
 		"label": "Tutorials",
@@ -116,13 +124,24 @@
 			"tools/bolt-python/tutorial/modals/modals"
 		]
 	},
-	{ "type": "html", "value": "<hr>" },
 	{
-		"type": "link",
+		"type": "html",
+		"value": "<hr>"
+	},
+	{
+		"type": "category",
 		"label": "Reference",
-		"href": "https://docs.slack.dev/tools/bolt-python/reference/index.html"
+		"items": [
+			{
+				"type": "autogenerated",
+				"dirName": "tools/bolt-python/reference"
+			}
+		]
+	},
+	{
+		"type": "html",
+		"value": "<hr>"
 	},
-	{ "type": "html", "value": "<hr>" },
 	{
 		"type": "category",
 		"label": "日本語 (日本)",
@@ -199,7 +218,9 @@
 			{
 				"type": "category",
 				"label": "レガシー（非推奨）",
-				"items": ["tools/bolt-python/ja-jp/legacy/steps-from-apps"]
+				"items": [
+					"tools/bolt-python/ja-jp/legacy/steps-from-apps"
+				]
 			}
 		]
 	}

docs/english/reference/adapter/aiohttp/index.md

@@ -0,0 +1,16 @@
+---
+sidebar_label: aiohttp
+title: slack_bolt.adapter.aiohttp
+---
+
+#### to\_bolt\_request
+
+```python
+async def to_bolt_request(request: web.Request) -> AsyncBoltRequest
+```
+
+#### to\_aiohttp\_response
+
+```python
+async def to_aiohttp_response(bolt_resp: BoltResponse) -> web.Response
+```

docs/english/reference/adapter/asgi/aiohttp/index.md

@@ -0,0 +1,58 @@
+---
+sidebar_label: aiohttp
+title: slack_bolt.adapter.asgi.aiohttp
+---
+
+## AsyncSlackRequestHandler Objects
+
+```python
+class AsyncSlackRequestHandler(SlackRequestHandler)
+```
+
+#### app: `AsyncApp`
+
+#### \_\_init\_\_
+
+```python
+def __init__(app: AsyncApp, path: str = '/slack/events')
+```
+
+Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers.
+This can be used for production deployment.
+
+With the default settings, `http://localhost:3000/slack/events`
+Run Bolt with [uvicron](https://www.uvicorn.org/)
+
+```python
+# Python
+app = AsyncApp()
+api = SlackRequestHandler(app)
+
+# bash
+export SLACK_SIGNING_SECRET=***
+export SLACK_BOT_TOKEN=xoxb-***
+uvicorn app:api --port 3000 --log-level debug
+```
+
+**Arguments**:
+
+- `app` _AsyncApp_ - Your bolt application
+- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`)
+
+#### dispatch
+
+```python
+async def dispatch(request: AsgiHttpRequest) -> BoltResponse
+```
+
+#### handle\_installation
+
+```python
+async def handle_installation(request: AsgiHttpRequest) -> BoltResponse
+```
+
+#### handle\_callback
+
+```python
+async def handle_callback(request: AsgiHttpRequest) -> BoltResponse
+```

docs/english/reference/adapter/asgi/async_handler.md

@@ -0,0 +1,58 @@
+---
+sidebar_label: async_handler
+title: slack_bolt.adapter.asgi.async_handler
+---
+
+## AsyncSlackRequestHandler Objects
+
+```python
+class AsyncSlackRequestHandler(SlackRequestHandler)
+```
+
+#### app: `AsyncApp`
+
+#### \_\_init\_\_
+
+```python
+def __init__(app: AsyncApp, path: str = '/slack/events')
+```
+
+Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers.
+This can be used for production deployment.
+
+With the default settings, `http://localhost:3000/slack/events`
+Run Bolt with [uvicron](https://www.uvicorn.org/)
+
+```python
+# Python
+app = AsyncApp()
+api = SlackRequestHandler(app)
+
+# bash
+export SLACK_SIGNING_SECRET=***
+export SLACK_BOT_TOKEN=xoxb-***
+uvicorn app:api --port 3000 --log-level debug
+```
+
+**Arguments**:
+
+- `app` _AsyncApp_ - Your bolt application
+- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`)
+
+#### dispatch
+
+```python
+async def dispatch(request: AsgiHttpRequest) -> BoltResponse
+```
+
+#### handle\_installation
+
+```python
+async def handle_installation(request: AsgiHttpRequest) -> BoltResponse
+```
+
+#### handle\_callback
+
+```python
+async def handle_callback(request: AsgiHttpRequest) -> BoltResponse
+```

docs/english/reference/adapter/asgi/base_handler.md

@@ -0,0 +1,38 @@
+---
+sidebar_label: base_handler
+title: slack_bolt.adapter.asgi.base_handler
+---
+
+## BaseSlackRequestHandler Objects
+
+```python
+class BaseSlackRequestHandler()
+```
+
+#### app: `Union[App, AsyncApp]`
+
+#### path: `str`
+
+#### dispatch
+
+```python
+async def dispatch(request: AsgiHttpRequest) -> BoltResponse
+```
+
+Dispatches a request to the Bolt App
+
+#### handle\_installation
+
+```python
+async def handle_installation(request: AsgiHttpRequest) -> BoltResponse
+```
+
+Handles installation of the OAuthFlow
+
+#### handle\_callback
+
+```python
+async def handle_callback(request: AsgiHttpRequest) -> BoltResponse
+```
+
+Handles the callback of the OAuthFlow

docs/english/reference/adapter/asgi/builtin/index.md

@@ -0,0 +1,56 @@
+---
+sidebar_label: builtin
+title: slack_bolt.adapter.asgi.builtin
+---
+
+## SlackRequestHandler Objects
+
+```python
+class SlackRequestHandler(BaseSlackRequestHandler)
+```
+
+#### \_\_init\_\_
+
+```python
+def __init__(app: App, path: str = '/slack/events')
+```
+
+Setup Bolt as an ASGI web framework, this will make your application compatible with ASGI web servers.
+This can be used for production deployment.
+
+With the default settings, `http://localhost:3000/slack/events`
+Run Bolt with [uvicron](https://www.uvicorn.org/)
+
+```python
+# Python
+app = App()
+api = SlackRequestHandler(app)
+
+# bash
+export SLACK_SIGNING_SECRET=***
+export SLACK_BOT_TOKEN=xoxb-***
+uvicorn app:api --port 3000 --log-level debug
+```
+
+**Arguments**:
+
+- `app` _App_ - Your bolt application
+- `path` _str_ - The path to handle request from Slack (Default: `/slack/events`)
+
+#### dispatch
+
+```python
+async def dispatch(request: AsgiHttpRequest) -> BoltResponse
+```
+
+#### handle\_installation
+
+```python
+async def handle_installation(request: AsgiHttpRequest) -> BoltResponse
+```
+
+#### handle\_callback
+
+```python
+async def handle_callback(request: AsgiHttpRequest) -> BoltResponse
+```

docs/english/reference/adapter/asgi/http_request.md

@@ -0,0 +1,30 @@
+---
+sidebar_label: http_request
+title: slack_bolt.adapter.asgi.http_request
+---
+
+## AsgiHttpRequest Objects
+
+```python
+class AsgiHttpRequest()
+```
+
+#### \_\_init\_\_
+
+```python
+def __init__(scope: scope_type, receive: Callable)
+```
+
+#### raw\_headers: `Iterable[Tuple[bytes, bytes]]`
+
+#### get\_headers
+
+```python
+def get_headers() -> Dict[str, Union[str, Sequence[str]]]
+```
+
+#### get\_raw\_body
+
+```python
+async def get_raw_body() -> str
+```