Skip to content

Commit ae61beb

Browse files
marcduikermarcduiker
authored
Merge pull request #4949 from marcduiker/remove-python-submodule
Add Python SDK docs and remove Python SDK submodule
2 parents bf4f7a7 + d71ab4d commit ae61beb

File tree

15 files changed

+1808
-6
lines changed

15 files changed

+1808
-6
lines changed

‎.gitmodules‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
1-
[submodule "sdkdocs/python"]
2-
path = sdkdocs/python
3-
url = https://github.com/dapr/python-sdk.git
41
[submodule "sdkdocs/php"]
52
path = sdkdocs/php
63
url = https://github.com/dapr/php-sdk.git

‎hugo.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -275,10 +275,10 @@ module:
275275
target: assets
276276
- source: daprdocs/archetypes
277277
target: archetypes
278-
- source: sdkdocs/python/daprdocs/content/en/python-sdk-docs
278+
- source: sdkdocs/python/content/en/python-sdk-docs
279279
target: content/developing-applications/sdks/python
280280
lang: en
281-
- source: sdkdocs/python/daprdocs/content/en/python-sdk-contributing
281+
- source: sdkdocs/python/content/en/python-sdk-contributing
282282
target: content/contributing/sdk-contrib/
283283
lang: en
284284
- source: sdkdocs/php/daprdocs/content/en/php-sdk-docs

‎sdkdocs/python‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎sdkdocs/python/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Dapr Python SDK documentation
2+
3+
This page covers how the documentation is structured for the Dapr Python SDK.
4+
5+
## Dapr Docs
6+
7+
All Dapr documentation is hosted at [docs.dapr.io](https://docs.dapr.io), including the docs for the [Python SDK](https://docs.dapr.io/developing-applications/sdks/python/). Head over there if you want to read the docs.
8+
9+
### Python SDK docs source
10+
11+
Although the docs site code and content is in the [docs repo](https://github.com/dapr/docs), the Python SDK content and images are within the `content` and `static` directories, respectively.
12+
13+
This allows separation of roles and expertise between maintainers, and makes it easy to find the docs files you are looking for.
14+
15+
## Writing Python SDK docs
16+
17+
To get up and running to write Python SDK docs, visit the [docs repo](https://github.com/dapr/docs) to initialize your environment. It will clone both the docs repo and this repo, so you can make changes and see it rendered within the site instantly, as well as commit and PR into this repo.
18+
19+
Make sure to read the [docs contributing guide](https://docs.dapr.io/contributing/contributing-docs/) for information on style/semantics/etc.
20+
21+
## Docs architecture
22+
23+
The docs site is built on [Hugo](https://gohugo.io), which lives in the docs repo. This repo is setup as a git submodule so that when the repo is cloned and initialized, the python repo, along with the docs, are cloned as well.
24+
25+
Then, in the Hugo configuration file, the `daprdocs/content` and `daprdocs/static` directories are redirected to the `daprdocs/developing-applications/sdks/python` and `static/python` directories, respectively. Thus, all the content within this repo is folded into the main docs site.

‎sdkdocs/python/content/en/python-sdk-contributing/python-contributing.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
type: docs
3+
title: "Contributing to the Python SDK"
4+
linkTitle: "Python SDK"
5+
weight: 3000
6+
description: Guidelines for contributing to the Dapr Python SDK
7+
---
8+
9+
When contributing to the [Python SDK](https://github.com/dapr/python-sdk) the following rules and best-practices should be followed.
10+
11+
## Examples
12+
13+
The `examples` directory contains code samples for users to run to try out specific functionality of the various Python SDK packages and extensions. When writing new and updated samples keep in mind:
14+
15+
- All examples should be runnable on Windows, Linux, and MacOS. While Python code is consistent among operating systems, any pre/post example commands should provide options through [tabpane]({{% ref "contributing-docs.md#tabbed-content" %}})
16+
- Contain steps to download/install any required pre-requisites. Someone coming in with a fresh OS install should be able to start on the example and complete it without an error. Links to external download pages are fine.
17+
18+
## Docs
19+
20+
The `daprdocs` directory contains the markdown files that are rendered into the [Dapr Docs](https://docs.dapr.io) website. When the documentation website is built this repo is cloned and configured so that its contents are rendered with the docs content. When writing docs keep in mind:
21+
22+
- All rules in the [docs guide]({{% ref contributing-docs.md %}}) should be followed in addition to these.
23+
- All files and directories should be prefixed with `python-` to ensure all file/directory names are globally unique across all Dapr documentation.
24+
25+
## Github Dapr Bot Commands
26+
27+
Checkout the [daprbot documentation](https://docs.dapr.io/contributing/daprbot/) for Github commands you can run in this repo for common tasks. For example, you can run the `/assign` (as a comment on an issue) to assign issues to a user or group of users.

‎sdkdocs/python/content/en/python-sdk-docs/_index.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
---
2+
type: docs
3+
title: "Dapr Python SDK"
4+
linkTitle: "Python"
5+
weight: 1000
6+
description: Python SDK packages for developing Dapr applications
7+
no_list: true
8+
cascade:
9+
github_repo: https://github.com/dapr/python-sdk
10+
github_subdir: daprdocs/content/en/python-sdk-docs
11+
path_base_for_github_subdir: content/en/developing-applications/sdks/python/
12+
github_branch: master
13+
---
14+
15+
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.
16+
17+
## Prerequisites
18+
19+
- [Dapr CLI]({{% ref install-dapr-cli.md %}}) installed
20+
- Initialized [Dapr environment]({{% ref install-dapr-selfhost.md %}})
21+
- [Python 3.9+](https://www.python.org/downloads/) installed
22+
23+
## Installation
24+
25+
To get started with the Python SDK, install the main Dapr Python SDK package.
26+
27+
{{< tabpane text=true >}}
28+
29+
{{% tab header="Stable" %}}
30+
<!--stable-->
31+
```bash
32+
pip install dapr
33+
```
34+
{{% /tab %}}
35+
36+
{{% tab header="Development" %}}
37+
<!--dev-->
38+
> **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.
39+
40+
```bash
41+
pip install dapr-dev
42+
```
43+
44+
{{% /tab %}}
45+
46+
{{< /tabpane >}}
47+
48+
49+
## Available subpackages
50+
51+
### SDK imports
52+
53+
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:
54+
55+
<div class="card-deck">
56+
<div class="card">
57+
<div class="card-body">
58+
<h5 class="card-title"><b>Client</b></h5>
59+
<p class="card-text">Write Python applications to interact with a Dapr sidecar and other Dapr applications, including stateful virtual actors in Python</p>
60+
<a href="{{% ref python-client %}}" class="stretched-link"></a>
61+
</div>
62+
</div>
63+
<div class="card">
64+
<div class="card-body">
65+
<h5 class="card-title"><b>Actors</b></h5>
66+
<p class="card-text">Create and interact with Dapr's Actor framework.</p>
67+
<a href="{{% ref python-actor %}}" class="stretched-link"></a>
68+
</div>
69+
</div>
70+
<div class="card">
71+
<div class="card-body">
72+
<h5 class="card-title"><b>Conversation</b></h5>
73+
<p class="card-text">Use the Dapr Conversation API (Alpha) for LLM interactions, tools, and multi-turn flows.</p>
74+
<a href="{{% ref conversation %}}" class="stretched-link"></a>
75+
</div>
76+
</div>
77+
</div>
78+
79+
Learn more about _all_ of the [available Dapr Python SDK imports](https://github.com/dapr/python-sdk/tree/master/dapr).
80+
81+
### SDK extensions
82+
83+
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.
84+
85+
<div class="card-deck">
86+
<div class="card">
87+
<div class="card-body">
88+
<h5 class="card-title"><b>gRPC</b></h5>
89+
<p class="card-text">Create Dapr services with the gRPC server extension.</p>
90+
<a href="{{% ref python-grpc %}}" class="stretched-link"></a>
91+
</div>
92+
</div>
93+
<div class="card">
94+
<div class="card-body">
95+
<h5 class="card-title"><b>FastAPI</b></h5>
96+
<p class="card-text">Integrate with Dapr Python virtual actors and pub/sub using the Dapr FastAPI extension.</p>
97+
<a href="{{% ref python-fastapi %}}" class="stretched-link"></a>
98+
</div>
99+
</div>
100+
<div class="card">
101+
<div class="card-body">
102+
<h5 class="card-title"><b>Flask</b></h5>
103+
<p class="card-text">Integrate with Dapr Python virtual actors using the Dapr Flask extension.</p>
104+
<a href="{{% ref python-sdk-extensions %}}" class="stretched-link"></a>
105+
</div>
106+
</div>
107+
<div class="card">
108+
<div class="card-body">
109+
<h5 class="card-title"><b>Workflow</b></h5>
110+
<p class="card-text">Author workflows that work with other Dapr APIs in Python.</p>
111+
<a href="{{% ref python-workflow %}}" class="stretched-link"></a>
112+
</div>
113+
</div>
114+
</div>
115+
116+
Learn more about [the Dapr Python SDK extensions](https://github.com/dapr/python-sdk/tree/master/ext).
117+
118+
## Try it out
119+
120+
Clone the Python SDK repo.
121+
122+
```bash
123+
git clone https://github.com/dapr/python-sdk.git
124+
```
125+
126+
Walk through the Python quickstarts, tutorials, and examples to see Dapr in action:
127+
128+
| SDK samples | Description |
129+
| ----------- | ----------- |
130+
| [Quickstarts]({{% ref quickstarts %}}) | Experience Dapr's API building blocks in just a few minutes using the Python SDK. |
131+
| [SDK samples](https://github.com/dapr/python-sdk/tree/master/examples) | Clone the SDK repo to try out some examples and get started. |
132+
| [Bindings tutorial](https://github.com/dapr/quickstarts/tree/master/tutorials/bindings) | See how Dapr Python SDK works alongside other Dapr SDKs to enable bindings. |
133+
| [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. |
134+
| [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. |
135+
| [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. |
136+
| [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. |
137+
| [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. |
138+
139+
140+
## More information
141+
142+
<div class="card-deck">
143+
<div class="card">
144+
<div class="card-body">
145+
<h5 class="card-title"><b>Serialization</b></h5>
146+
<p class="card-text">Learn more about serialization in Dapr SDKs.</p>
147+
<a href="{{% ref sdk-serialization %}}" class="stretched-link"></a>
148+
</div>
149+
</div>
150+
<div class="card">
151+
<div class="card-body">
152+
<h5 class="card-title"><b>PyPI</b></h5>
153+
<p class="card-text">Python Package Index</p>
154+
<a href="https://pypi.org/user/dapr.io/" class="stretched-link"></a>
155+
</div>
156+
</div>
157+
</div>

0 commit comments

Comments
 (0)