[docs] Reformat index page (#580)

* reformat index page Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * quick freshness pass on python client doc Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * edit based on bernd review Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * updates per bernd discussion Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * revert a bit Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * add note that workflow is in alpha Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * move workflow doc to extensions node Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * bernd review Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * update terminology, clean up docs org in toc Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> * forgot one url ref Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> --------- Signed-off-by: Hannah Hunter <hannahhunter@microsoft.com> Co-authored-by: Bernd Verst <github@bernd.dev>
dapr · Jul 18, 2023 · 152de30 · 152de30
1 parent f2de407
commit 152de30
Show file tree

Hide file tree

Showing 9 changed files with 185 additions and 43 deletions.
diff --git a/daprdocs/content/en/python-sdk-docs/_index.md b/daprdocs/content/en/python-sdk-docs/_index.md
@@ -12,48 +12,140 @@ cascade:
   github_branch: master
 ---
 
-Dapr offers a variety of packages to help with the development of Python applications. Using them you can create Python clients, servers, and virtual actors with Dapr.
+Dapr offers a variety of subpackages to help with the development of Python applications. Using them you can create Python clients, servers, and virtual actors with Dapr.
 
-## Available packages
+## Prerequisites
 
-- [**Dapr client**]({{< ref python-client.md >}}) for writing Python applications to interact with the Dapr sidecar and other Dapr applications
-- [**Dapr actor**]({{< ref python-actor.md >}}) for creating and interacting with stateful virtual actors in Python
-- [**Extensions**]({{< ref python-sdk-extensions >}}) for adding Dapr capabilities to other Python frameworks
-    - [**gRPC extension**]({{< ref python-grpc.md >}}) for creating a gRPC server with Dapr
-    - [**FastAPI extension**]({{< ref python-fastapi.md >}}) for adding Dapr actor capabilities to FastAPI applications
-    - [**Flask extension**]({{< ref python-flask.md >}}) for adding Dapr actor capabilities to Flask applications
+- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
+- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
+- [Python 3.7+](https://www.python.org/downloads/) installed
 
-## Install the Dapr module
+## Installation
+
+To get started with the Python SDK, install the main Dapr Python SDK package. 
 
 {{< tabs Stable Development>}}
 
 {{% codetab %}}
+<!--stable-->
 ```bash
 pip install dapr
 ```
 {{% /codetab %}}
 
 {{% codetab %}}
-{{% alert title="Note" color="warning" %}}
-The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK before installing the dapr-dev package.
+<!--dev-->
+> **Note:** The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK before installing the dapr-dev package.
 {{% /alert %}}
 
 ```bash
 pip install dapr-dev
 ```
+
 {{% /codetab %}}
 
 {{< /tabs >}}
 
+
+## Available subpackages
+
+### SDK imports
+
+Python SDK imports are subpackages included with the main SDK install, but need to be imported when used. The most common imports provided by the Dapr Python SDK are:
+
+<div class="card-deck">
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>Client</b></h5>
+      <p class="card-text">Write Python applications to interact with a Dapr sidecar and other Dapr applications, including stateful virtual actors in Python</p>
+      <a href="{{< ref python-client >}}" class="stretched-link"></a>
+    </div>
+  </div>
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>Actors</b></h5>
+      <p class="card-text">Create and interact with Dapr's Actor framework.</p>
+      <a href="{{< ref python-actor >}}" class="stretched-link"></a>
+    </div>
+  </div>
+</div>
+
+Learn more about _all_ of the [available Dapr Python SDK imports](https://github.com/dapr/python-sdk/tree/master/dapr). 
+
+### SDK extensions
+
+SDK extensions mainly work as utilities for receiving pub/sub events, programatically creating pub/sub subscriptions, and handling input binding events. While you can acheive all of these tasks without an extension, using a Python SDK extension proves convenient.
+
+<div class="card-deck">
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>gRPC</b></h5>
+      <p class="card-text">Create Dapr services with the gRPC server extension.</p>
+      <a href="{{< ref python-grpc >}}" class="stretched-link"></a>
+    </div>
+  </div>
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>FastAPI</b></h5>
+      <p class="card-text">Integrate with Dapr Python virtual actors and pub/sub using the Dapr FastAPI extension.</p>
+      <a href="{{< ref python-fastapi >}}" class="stretched-link"></a>
+    </div>
+  </div>
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>Flask</b></h5>
+      <p class="card-text">Integrate with Dapr Python virtual actors using the Dapr Flask extension.</p>
+      <a href="{{< ref python-sdk-extensions >}}" class="stretched-link"></a>
+    </div>
+  </div>
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>Workflow</b></h5>
+      <p class="card-text">Author workflows that work with other Dapr APIs in Python.</p>
+      <a href="{{< ref python-workflow >}}" class="stretched-link"></a>
+    </div>
+  </div>
+</div>
+
+Learn more about [the Dapr Python SDK extensions](https://github.com/dapr/python-sdk/tree/master/ext).
+
 ## Try it out
 
-Clone the Python SDK repo to try out some of the [examples](https://github.com/dapr/python-sdk/tree/master/examples).
+Clone the Python SDK repo.
 
 ```bash
 git clone https://github.com/dapr/python-sdk.git
 ```
 
+Walk through the Python quickstarts, tutorials, and examples to see Dapr in action:
+
+| SDK samples | Description |
+| ----------- | ----------- |
+| [Quickstarts]({{< ref quickstarts >}}) | Experience Dapr's API building blocks in just a few minutes using the Python SDK. |
+| [SDK samples](https://github.com/dapr/python-sdk/tree/master/examples) | Clone the SDK repo to try out some examples and get started. |
+| [Bindings tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/bindings) | See how Dapr Python SDK works alongside other Dapr SDKs to enable bindings. |
+| [Distributed Calculator tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/distributed-calculator/python) | Use the Dapr Python SDK to handle method invocation and state persistent capabilities. |
+| [Hello World tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-world) | Learn how to get Dapr up and running locally on your machine with the Python SDK. |
+| [Hello Kubernetes tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/hello-kubernetes) | Get up and running with the Dapr Python SDK in a Kubernetes cluster. |
+| [Observability tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/observability) | Explore Dapr's metric collection, tracing, logging and health check capabilities using the Python SDK. |
+| [Pub/sub tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/pub-sub) | See how Dapr Python SDK works alongside other Dapr SDKs to enable pub/sub applications. |
+
+
 ## More information
 
-- [Python Package Index (PyPI)](https://pypi.org/user/dapr.io/)
-- [Dapr SDK serialization]({{< ref sdk-serialization.md >}})
+<div class="card-deck">
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>Serialization</b></h5>
+      <p class="card-text">Learn more about serialization in Dapr SDKs.</p>
+      <a href="{{< ref sdk-serialization >}}" class="stretched-link"></a>
+    </div>
+  </div>
+  <div class="card">
+    <div class="card-body">
+      <h5 class="card-title"><b>PyPI</b></h5>
+      <p class="card-text">Python Package Index</p>
+      <a href="https://pypi.org/user/dapr.io/" class="stretched-link"></a>
+    </div>
+  </div>
+</div>
diff --git a/daprdocs/content/en/python-sdk-docs/python-actor.md b/daprdocs/content/en/python-sdk-docs/python-actor.md
@@ -13,7 +13,7 @@ The Dapr actor package allows you to interact with Dapr virtual actors from a Py
 - [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
 - Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
 - [Python 3.7+](https://www.python.org/downloads/) installed
-- [Dapr Python module]({{< ref "python#install-the0dapr-module" >}}) installed
+- [Dapr Python package]({{< ref "python#installation" >}}) installed
 
 ## Actor interface
 

diff --git a/daprdocs/content/en/python-sdk-docs/python-client.md b/daprdocs/content/en/python-sdk-docs/python-client.md
@@ -8,16 +8,18 @@ description: How to get up and running with the Dapr Python SDK
 
 The Dapr client package allows you to interact with other Dapr applications from a Python application.
 
-## Pre-requisites
+{{% alert title="Note" color="primary" %}}
+ If you haven't already, [try out one of the quickstarts]({{< ref quickstarts >}}) for a quick walk-through on how to use the Dapr Python SDK with an API building block.
 
-- [Dapr CLI]({{< ref install-dapr-cli.md >}}) installed
-- Initialized [Dapr environment]({{< ref install-dapr-selfhost.md >}})
-- [Python 3.7+](https://www.python.org/downloads/) installed
-- [Dapr Python module]({{< ref "python#install-the0dapr-module" >}}) installed
+{{% /alert %}}
+
+## Prerequisites
+
+[Install the Dapr Python package]({{< ref "python-sdk-docs/_index.md" >}}) before getting started.
 
 ## Import the client package
 
-The dapr package contains the `DaprClient` which will be used to create and use a client.
+The `dapr` package contains the `DaprClient`, which is used to create and use a client.
 
 ```python
 from dapr.clients import DaprClient
@@ -42,7 +44,7 @@ with DaprClient() as d:
 ```
 
 - For a full guide on service invocation visit [How-To: Invoke a service]({{< ref howto-invoke-discover-services.md >}}).
-- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/invoke-simple) for code samples and instructions to try out service invocation
+- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/invoke-simple) for code samples and instructions to try out service invocation.
 
 ### Save & get application state
 
@@ -61,7 +63,7 @@ with DaprClient() as d:
 ```
 
 - For a full list of state operations visit [How-To: Get & save state]({{< ref howto-get-save-state.md >}}).
-- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/state_store) for code samples and instructions to try out state management
+- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/state_store) for code samples and instructions to try out state management.
 
 ### Query application state (Alpha)
 
@@ -95,7 +97,7 @@ with DaprClient() as d:
 
 ### Publish & subscribe to messages
 
-##### Publish messages
+#### Publish messages
 
 ```python
 from dapr.clients import DaprClient
@@ -104,7 +106,7 @@ with DaprClient() as d:
     resp = d.publish_event(pubsub_name='pubsub', topic_name='TOPIC_A', data='{"message":"Hello World"}')
 ```
 
-##### Subscribe to messages
+#### Subscribe to messages
 
 ```python
 from cloudevents.sdk.event import v1
@@ -143,7 +145,7 @@ with DaprClient() as d:
 ```
 
 - For a full guide on output bindings visit [How-To: Use bindings]({{< ref howto-bindings.md >}}).
-- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/invoke-binding) for code samples and instructions to try out output bindings
+- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/invoke-binding) for code samples and instructions to try out output bindings.
 
 ### Retrieve secrets
 
@@ -157,7 +159,9 @@ with DaprClient() as d:
 - For a full guide on secrets visit [How-To: Retrieve secrets]({{< ref howto-secrets.md >}}).
 - Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/secret_store) for code samples and instructions to try out retrieving secrets
 
-### Get configuration
+### Configuration
+
+#### Get configuration
 
 ```python
 from dapr.clients import DaprClient
@@ -167,7 +171,7 @@ with DaprClient() as d:
     configuration = d.get_configuration(store_name='configurationstore', keys=['orderId'], config_metadata={})
 ```
 
-### Subscribe to configuration
+#### Subscribe to configuration
 
 ```python
 import asyncio
@@ -198,7 +202,7 @@ asyncio.run(executeConfiguration())
 ```
 
 - Learn more about managing configurations via the [How-To: Manage configuration]({{< ref howto-manage-configuration.md >}}) guide.
-- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/configuration) for code samples and instructions to try out configuration
+- Visit [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples/configuration) for code samples and instructions to try out configuration.
 
 ### Distributed Lock
 
@@ -316,4 +320,4 @@ def main():
 
 
 ## Related links
-- [Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples)
+[Python SDK examples](https://github.com/dapr/python-sdk/tree/master/examples)
diff --git a/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/_index.md b/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/_index.md
@@ -2,6 +2,6 @@
 type: docs
 title: "Dapr Python SDK extensions"
 linkTitle: "Extensions"
-weight: 20000
+weight: 30000
 description: Python SDK for developing Dapr applications
 ---
diff --git a/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/python-fastapi.md b/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/python-fastapi.md
@@ -6,11 +6,11 @@ weight: 200000
 description: How to create Dapr Python virtual actors and pubsub with the FastAPI extension
 ---
 
-The Dapr Python SDK provides integration with FastAPI using the `dapr-ext-fastapi` module
+The Dapr Python SDK provides integration with FastAPI using the `dapr-ext-fastapi` extension.
 
 ## Installation
 
-You can download and install the Dapr FastAPI extension module with:
+You can download and install the Dapr FastAPI extension with:
 
 {{< tabs Stable Development>}}
 
@@ -22,7 +22,7 @@ pip install dapr-ext-fastapi
 
 {{% codetab %}}
 {{% alert title="Note" color="warning" %}}
-The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the dapr-dev package.
+The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the `dapr-dev` package.
 {{% /alert %}}
 
 ```bash

diff --git a/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/python-flask.md b/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/python-flask.md
@@ -6,11 +6,11 @@ weight: 300000
 description: How to create Dapr Python virtual actors with the Flask extension
 ---
 
-The Dapr Python SDK provides integration with Flask using the `flask-dapr` module
+The Dapr Python SDK provides integration with Flask using the `flask-dapr` extension.
 
 ## Installation
 
-You can download and install the Dapr Flask extension module with:
+You can download and install the Dapr Flask extension with:
 
 {{< tabs Stable Development>}}
 
@@ -22,7 +22,7 @@ pip install flask-dapr
 
 {{% codetab %}}
 {{% alert title="Note" color="warning" %}}
-The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the dapr-dev package.
+The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the `dapr-dev` package.
 {{% /alert %}}
 
 ```bash

diff --git a/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/python-grpc.md b/daprdocs/content/en/python-sdk-docs/python-sdk-extensions/python-grpc.md
@@ -2,15 +2,15 @@
 type: docs
 title: "Getting started with the Dapr Python gRPC service extension"
 linkTitle: "gRPC"
-weight: 20000
-description: How to get up and running with the Dapr Python gRPC extension package
+weight: 100000
+description: How to get up and running with the Dapr Python gRPC extension
 ---
 
-The Dapr Python SDK provides a built in gRPC server extension module, `dapr.ext.grpc`, for creating Dapr services.
+The Dapr Python SDK provides a built in gRPC server extension, `dapr.ext.grpc`, for creating Dapr services.
 
 ## Installation
 
-You can download and install the Dapr gRPC server extension module with:
+You can download and install the Dapr gRPC server extension with:
 
 {{< tabs Stable Development>}}
 
@@ -22,7 +22,7 @@ pip install dapr-ext-grpc
 
 {{% codetab %}}
 {{% alert title="Note" color="warning" %}}
-The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the dapr-dev package.
+The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the `dapr-dev` package.
 {{% /alert %}}
 
 ```bash

diff --git a/...docs/content/en/python-sdk-docs/python-sdk-extensions/python-workflow/_index.md b/...docs/content/en/python-sdk-docs/python-sdk-extensions/python-workflow/_index.md
@@ -0,0 +1,42 @@
+---
+type: docs
+title: "Dapr Python SDK integration with Dapr Workflow extension"
+linkTitle: "Dapr Workflow"
+weight: 400000
+description: How to get up and running with the Dapr Workflow extension
+no_list: true
+---
+
+{{% alert title="Note" color="primary" %}}
+Dapr Workflow is currently in alpha.
+{{% /alert %}}
+
+The Dapr Python SDK provides a built in Dapr Workflow extension, `dapr.ext.workflow`, for creating Dapr services.
+
+## Installation
+
+You can download and install the Dapr Workflow extension with:
+
+{{< tabs Stable Development>}}
+
+{{% codetab %}}
+```bash
+pip install dapr-ext-workflow
+```
+{{% /codetab %}}
+
+{{% codetab %}}
+{{% alert title="Note" color="warning" %}}
+The development package will contain features and behavior that will be compatible with the pre-release version of the Dapr runtime. Make sure to uninstall any stable versions of the Python SDK extension before installing the `dapr-dev` package.
+{{% /alert %}}
+
+```bash
+pip3 install dapr-ext-workflow-dev
+```
+{{% /codetab %}}
+
+{{< /tabs >}}
+
+## Next steps
+
+{{< button text="Getting started with the Dapr Workflow Python SDK" page="python-workflow.md" >}}