Update docstring and add the api-docs generator script

Author: seratch

.github/maintainers_guide.md

@@ -109,6 +109,12 @@ $ ngrok http 3000 --subdomain {your-domain}
 
 ### Releasing
 
+#### Generate API documents
+
+```bash
+./scripts/generate_api_docs.sh
+```
+
 #### test.pypi.org deployment
 
 ##### $HOME/.pypirc

docs/_includes/sidebar.html

@@ -23,6 +23,9 @@
     <a href="{{ site.url | append: site.baseurl | append: localized_base_url  }}/tutorial/getting-started">
       <li class="title">{{ site.t[page.lang].start }}</li>
     </a>
+    <a href="{{ site.url | append: site.baseurl | append: localized_base_url  }}/api-docs/slack_bolt/" target="_blank">
+      <li class="title">API Documents</li>
+    </a>
   </ul>
 
   <ul class="sidebar-section">

scripts/generate_api_docs.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+# Generate API documents from the latest source code
+
+script_dir=`dirname $0`
+cd ${script_dir}/..
+
+pip install pdoc3
+rm -rf docs/api-docs
+pdoc slack_bolt --html -o docs/api-docs
+open docs/api-docs/slack_bolt/index.html

slack_bolt/__init__.py

@@ -1,3 +1,10 @@
+"""
+A Python framework to build Slack apps in a flash with the latest platform features. Read the [getting started guide](https://slack.dev/bolt-python/tutorial/getting-started) and look at our [code examples](https://github.com/slackapi/bolt-python/tree/main/examples) to learn how to build apps using Bolt.
+
+* Website: https://slack.dev/bolt-python/
+* GitHub repository: https://github.com/slackapi/bolt-python
+* The class representing a Bolt app: `slack_bolt.app.app`
+"""
 # Don't add async module imports here
 from .app import App  # noqa
 from .context import BoltContext  # noqa

slack_bolt/adapter/__init__.py

@@ -0,0 +1,2 @@
+"""Adapter modules for running Bolt apps along with Web frameworks or Socket Mode.
+"""

slack_bolt/app/__init__.py

@@ -1,2 +1,9 @@
+"""Application interface in Bolt.
+
+For most use cases, we recommend using `slack_bolt.app.app`.
+If you already have knowledge about asyncio and prefer the programming model,
+you can use `slack_bolt.app.async_app` for building async apps.\
+"""
+
 # Don't add async module imports here
 from .app import App  # type: ignore

slack_bolt/app/app.py

@@ -19,10 +19,13 @@ def __init__(  # type:ignore
         path: str,
         app: "AsyncApp",  # type:ignore
     ):
-        """Standalone AIOHTTP Web Server
+        """Standalone AIOHTTP Web Server.
+        Refer to https://docs.aiohttp.org/en/stable/web.html for details of AIOHTTP.
 
-        Refer to AIOHTTP documents for details.
-        https://docs.aiohttp.org/en/stable/web.html
+        Args:
+            port: The port to listen on
+            path: The path to receive incoming requests from Slack
+            app: The `AsyncApp` instance that is used for processing requests
         """
         self.port = port
         self.path = path
@@ -70,10 +73,7 @@ async def handle_post_requests(self, request: web.Request) -> web.Response:
         return await to_aiohttp_response(bolt_resp)
 
     def start(self) -> None:
-        """Starts a new web server process.
-
-        :return: None
-        """
+        """Starts a new web server process."""
         if self.bolt_app.logger.level > logging.INFO:
             print(get_boot_message())
         else:

slack_bolt/app/async_app.py

@@ -1,3 +1,49 @@
+"""Module for creating asyncio based apps
+
+### Creating an async app
+
+If you'd prefer to build your app with [asyncio](https://docs.python.org/3/library/asyncio.html), you can import the [AIOHTTP](https://docs.aiohttp.org/en/stable/) library and call the `AsyncApp` constructor. Within async apps, you can use the async/await pattern.
+
+```bash
+# Python 3.6+ required
+python -m venv .venv
+source .venv/bin/activate
+
+pip install -U pip
+# aiohttp is required
+pip install slack_bolt aiohttp
+```
+
+In async apps, all middleware/listeners must be async functions. When calling utility methods (like `ack` and `say`) within these functions, it's required to use the `await` keyword.
+
+```python
+# Import the async app instead of the regular one
+from slack_bolt.async_app import AsyncApp
+
+app = AsyncApp()
+
+@app.event("app_mention")
+async def event_test(body, say, logger):
+    logger.info(body)
+    await say("What's up?")
+
+@app.command("/hello-bolt-python")
+async def command(ack, body, respond):
+    await ack()
+    await respond(f"Hi <@{body['user_id']}>!")
+
+if __name__ == "__main__":
+    app.start(3000)
+```
+
+If you want to use another async Web framework (e.g., Sanic, FastAPI, Starlette), take a look at the built-in adapters and their examples.
+
+* [The Bolt app examples](https://github.com/slackapi/bolt-python/tree/main/examples)
+* [The built-in adapters](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter)
+Apps can be run the same way as the synchronous example above. If you'd prefer another async Web framework (e.g., Sanic, FastAPI, Starlette), take a look at [the built-in adapters](https://github.com/slackapi/bolt-python/tree/main/slack_bolt/adapter) and their corresponding [examples](https://github.com/slackapi/bolt-python/tree/main/examples).
+
+Refer to `slack_bolt.app.async_app` for more details.
+"""
 from .app.async_app import AsyncApp  # noqa
 from .context.ack.async_ack import AsyncAck  # noqa
 from .context.async_context import AsyncBoltContext  # noqa