Add next-gen future documentation

.gitignore

@@ -29,6 +29,7 @@ coverage.xml
 .python-version
 pip
 .mypy_cache/
+.ruby-version
 
 # JetBrains PyCharm settings
 .idea/

docs/Gemfile

@@ -1,3 +1,4 @@
 source 'https://rubygems.org'
 gem 'github-pages', group: :jekyll_plugins
 gem 'dotenv'
+gem 'webrick'

docs/_config.yml

@@ -18,10 +18,12 @@ collections:
   tutorials:
     output: true
     permalink: /tutorials/:slug
+  future:
+    output: true
+    permalink: /future/:slug
 
 defaults:
-  -
-    scope:
+  - scope:
       path: ""
     values:
       layout: "default"
@@ -35,12 +37,16 @@ t:
     advanced: Advanced concepts
     start: Getting started
     contribute: Contributing
+    beta: BETA
+    legacy: LEGACY
   ja-jp:
     basic: 基本的な概念
     steps: ワークフローステップ
     advanced: 応用コンセプト
     start: Bolt 入門ガイド
     contribute: 貢献
+    beta: BETA
+    legacy: LEGACY
 
 # Metadata
 repo_name: bolt-python
@@ -56,7 +62,6 @@ google_tag_manager: GTM-KFZ5MK7
 markdown: kramdown
 kramdown:
   parse_block_html: true
-  parse_span_html: true
   syntax_highlighter_opts:
     block:
       line_numbers: true

docs/_future/concepts.md

@@ -0,0 +1,14 @@
+---
+title: Slack developer beta
+lang: en
+slug: concepts
+order: 0
+layout: future
+permalink: /future/concepts
+---
+# Slack developer beta concepts <span class="label-beta">BETA</span>
+
+<div class="section-content">
+This page contains all the concepts that are necessary to allow you to use the next-gen Slack features in Python.
+<p class="alert alert_info"><ts-icon class="ts_icon_info_circle"></ts-icon>Our next-generation platform is currently in beta. <a href="https://api.slack.com/future/survey" target="_blank">Your feedback is most welcome</a> - all feedback will help shape the future platform experience!</p>
+</div>

docs/_future/deploy_your_app.md

@@ -0,0 +1,16 @@
+---
+
+title: Deploy your app
+lang: en
+slug: deploy-your-app
+order: 6
+layout: tutorial
+permalink: /tutorial/deploy-your-app
+---
+# Deploy your app <span class="label-beta">BETA</span>
+
+<div class="section-content">
+Instructions for deploying your next-generation Bolt Python application to third-party infrastructure are coming soon! Stay tuned.
+
+<p class="alert alert_info"><ts-icon class="ts_icon_info_circle"></ts-icon>Our next-generation platform is currently in beta. <a href="https://api.slack.com/future/survey" target="_blank">Your feedback is most welcome</a> - all feedback will help shape the future platform experience!</p>
+</div>

docs/_future/getting_started_future.md

@@ -0,0 +1,146 @@
+---
+title: Getting started
+order: 1
+slug: getting-started-future
+lang: en
+layout: tutorial
+permalink: /tutorial/getting-started-future
+---
+
+## Getting started <span class="label-beta">BETA</span>
+
+<div class="section-content">
+This guide will cover how to get started with your next-gen platform using Bolt for Python, by setting up the Slack CLI and installing the required dependencies.
+
+Find out about the next-generation platform on Slack's <a href="https://api.slack.com/future/intro" target="_blank">official introduction page.</a>
+</div>
+
+---
+
+### Limitations
+
+Bolt for Python supports app development using next-gen platform features like Functions, Workflows and tools such as the Slack CLI alongside all current generally available Slack Platform features.
+
+#### We do not yet support
+
+- Deployment to secure and managed Slack infrastructure.
+- Datastores API <a href="https://api.slack.com/future/datastores" target="_blank">Datastores</a> functionality.
+
+> If you'd like to deploy your app with Slack infrastructure, consider building your next-generation application with the Deno Slack API. You can get started with that <a href="https://api.slack.com/future/get-started" target="_blank">here</a>.
+
+---
+
+### Setting up {#setting-up}
+
+#### Slack CLI {#setting-up-cli}
+
+To build a next-generation app with Bolt for Python, you'll need to get the Slack CLI.
+
+Install the Slack CLI by following this <a href="https://api.slack.com/future/quickstart" target="_blank">Quickstart</a>. Since we won't be using Deno to build our next-generation app, you can skip any instructions related to installing Deno or creating an app using a Deno template. Once you've logged into the CLI using `slack login` and verified your login using `slack auth list`, you can proceed with the instructions in this guide.
+
+#### Dependencies {#setting-up-dependencies}
+
+Once the CLI is set up, make sure your machine has the most recent version of <a href="https://www.python.org/" target="_blank">Python</a> installed. You can install Python through a package manager (such as <a href="https://brew.sh/" target="_blank">Homebrew</a> for Mac) or directly from the <a href="https://www.python.org/downloads/" target="_blank">website</a>.
+
+---
+
+### Create a new app {#create-app}
+
+Before you start developing with Bolt, you'll want to create a Slack app.
+
+To create the app, you'll run the following command:
+
+```bash
+slack create my-app -t slack-samples/bolt-python-starter-template -b future
+```
+
+This command creates an app through the CLI by cloning a specified template. In this case, the template is the <a href="https://github.com/slack-samples/bolt-python-starter-template/tree/future" target="_blank">Bolt for Python Starter Template</a> on the `future` branch. This starter template includes a "Hello World" example that demonstrates how to use <a href="/bolt-python/future/concepts#built-in-functions" target="_blank">built-in</a> and <a href="/bolt-python/future/concepts#functions" target="_blank">custom</a> Functions, <a href="https://api.slack.com/future/triggers" target="_blank">Triggers</a> and <a href="/bolt-python/future/concepts#manifest-workflows" target="_blank">Workflows</a>.
+
+Once the app is successfully created, you should see a message like this:
+
+```text
+✨ my-app successfully created
+
+🧭 Explore your project's README.md for documentation and code samples, and at any time run slack help to display a list of available commands
+
+🧑‍🚀 Follow the steps below to try out your new project
+
+1️⃣  Change into your project directory with: cd my-app
+
+2️⃣  Develop locally and see changes in real-time with: slack run
+
+3️⃣  When you're ready to deploy for production use: slack deploy
+
+🔔 If you leave the workspace, you won’t be able to manage any apps you’ve deployed to it. Apps you deploy will belong to the workspace even if you leave the workspace
+```
+
+---
+
+### Set up your trigger {#setup-trigger}
+
+As mentioned, this app comes with preexisting functionality - it uses Functions, Workflows and a Trigger set up to kick things off. Let's run a command to initialize that Trigger via the CLI.
+
+First, make sure you're in the project directory in your command line: `cd my-app`
+
+Then, run the following command to create a Trigger:
+
+```bash
+slack triggers create --trigger-def "triggers/sample-trigger.json"      
+```
+
+The above command will create a trigger for the selected workspace. Make sure to select the workspace you want and that it is appended by `(dev)`. This will create a dev instance of your app. Once the trigger is successfully created, you should see an output like this:
+
+```bash
+⚡ Trigger created
+   Trigger ID:   [ID]
+   Trigger Type: shortcut
+   Trigger Name: Sample Trigger
+   URL: https://slack.com/shortcuts/[ID]/[Some ID]
+```
+
+The provided URL will be what you use to run your Trigger. Copy this URL and save it somewhere; you'll need it for later.
+
+---
+
+### Run your app {#run-your-app}
+
+Now that your app and Trigger are successfully created, let's try running it!
+
+```bash
+# install the required project dependencies
+pip install -r requirements.txt
+
+# start a local development server
+slack run
+```
+
+Executing `pip install -r requirements.txt` installs all the project requirements to your machine.
+
+Executing `slack run` starts a local development server, syncing changes to your workspace's development version of your app.
+
+You'll be prompted to select a workspace to install the app to&mdash;select the development instance of your workspace (you'll know it's the development version because the name has the string `(dev)` appended).
+
+> 💡 If you don't see the workspace you'd like to use in the list, you can `CTRL + C` out of the `slack run` command and run `slack auth login`. This will allow you to authenticate in your desired workspace to have it show up in the list for `slack run`.
+
+Once the app is successfully ran, you'll see output in your Terminal to indicate it's running, similar to what you would see with any other Bolt for Python app. You can search for the `⚡️ Bolt app is running! ⚡️` message to make sure that your app has successfully started up.
+
+### Trigger your app's workflow {#trigger-workflow}
+
+With your app running, access your workspace and paste the URL from the Trigger you created in the [previous step](/bolt-python/tutorial/getting-started-future#setup-trigger) into a message in a public channel.
+
+> 💡 App Triggers are automatically saved as a channel bookmark under "Workflows" for easy access.
+
+Send the message and click the "Run" button that appears. A modal will appear prompting you to enter information to greet someone in your Slack workspace. Fill out the requested information.
+
+![Hello World modal](https://slack.dev/bolt-js/assets/hello-world-modal.png "Hello World modal")
+
+Then, submit the form. In the specified channel submitted in the form, you should receive a message from the app tagging the submitted user. The message will also contain a randomly generated greeting and the message you wrote in the form.
+
+The full app flow can be seen here:
+![Hello World app](https://slack.dev/bolt-js/assets/hello-world-demo.gif "Hello World app")
+
+---
+
+### Next steps {#next-steps}
+
+Now we have a working instance of a next-generation app in your workspace and you've seen it in action! You can explore on your own and dive into the code yourself <a href="https://github.com/slack-samples/bolt-python-starter-template/tree/future" target="_blank">here</a> or continue your learning journey by diving into [App Manifests](/bolt-python/future/concepts#manifests) or looking into adding more [Functions](/bolt-python/future/concepts#functions), [Workflows](/bolt-python/future/concepts#manifest-workflows), and [Triggers](#setup-trigger) to your app!

docs/_future/listening_responding_functions.md

@@ -0,0 +1,105 @@
+---
+title: Listening & responding to functions
+lang: en
+slug: functions
+order: 5
+layout: future
+---
+
+<div class="section-content">
+
+Your app can use the `function()` method to listen to incoming function requests. The method requires a function `callback_id` of type `str`. This `callback_id` must also be defined in your [Function](/bolt-python/future/concepts#manifest-functions) definition. Functions must eventually be completed with the `complete()` function to inform Slack that your app has processed the function request. `complete()` requires **one of two** keyword arguments: `outputs` or `error`. There are two ways to complete a Function with `complete()`:
+
+* `outputs` of type `dict` completes your function **successfully** and provide a dictionary containing the outputs of your function as defined in the app's manifest.
+* `error` of type `str` completes your function **unsuccessfully** and provides a message containing information regarding why your function was not successful.
+
+</div>
+
+<div>
+<span class="annotation">Refer to <a href="https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html" target="_blank">the module document</a> to learn the available listener arguments.</span>
+```python
+# The sample function simply outputs an input
+@app.function("sample_function")
+def sample_func(event, complete: Complete):
+    try:
+        message = event["inputs"]["message"]
+        complete(
+            outputs={
+                "updatedMsg": f":wave: You submitted the following message: \n\n>{message}"
+            }
+        )
+    except Exception as e:
+        complete(error="Cannot submit the message")
+        raise e
+```
+</div>
+
+<details class="secondary-wrapper">
+<summary markdown="0">
+<h4 class="secondary-header">Function Interactivity</h4>
+</summary>
+
+<div class="secondary-content">
+
+The `function()` method returns a `SlackFunction` decorator object. This object can be used by your app to set up interactive listeners such as [actions](/bolt-python/concepts#action-respond) and [views](/bolt-python/concepts#view_submissions). These listeners listen to events created during the handling of your `function` event. Additionally, they will only be called when a user interacts with a block element that has the following attributes:
+
+* It was created during the handling of a `function` event.
+* The `action_id` matches the interactive listeners `action_id`.
+
+These listeners behave similarly to the ones assigned directly to your app. the notable difference is that `complete()` must be called once your function is completed.
+
+</div>
+
+```python
+# Your listener will be called when your function "sample_function" is triggered from a workflow
+# When triggered a message containing a button with an action_id "approve_button" is posted
+@app.function("sample_function")
+def sample_func(event, complete: Complete):
+    try:
+        client.chat_postMessage(
+            channel="a-channel-id",
+            text="A new button appears",
+            blocks=[
+                {
+                    "type": "actions",
+                    "block_id": "approve-button",
+                    "elements": [
+                        {
+                            "type": "button",
+                            "text": {
+                                "type": "plain_text",
+                                "text": "Click",
+                            },
+                            "action_id": "sample_action",
+                            "style": "primary",
+                        },
+                    ],
+                },
+            ],
+        )
+    except Exception as e:
+        complete(error="Cannot post message")
+        raise e
+
+# Your listener will be called when a block element
+#   - Created by your "sample_func"
+#   - With the action_id "sample_action"
+# is triggered
+@sample_func.action("sample_action")
+def update_message(ack, body, client, complete):
+    try:
+        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"],
+            )
+        complete()
+    except Exception as e:
+        logger.error(e)
+        complete(error="Cannot react to message")
+        raise e
+```
+
+</details>