This is an automated email from the ASF dual-hosted git repository.
bossenti pushed a commit to branch chore/improve-getting-started-python
in repository https://gitbox.apache.org/repos/asf/streampipes.git
commit b231f2c4f1eb03f9e7606bd2b631fb891512b626
Author: bossenti <bo...@posteo.de>
AuthorDate: Sat Feb 18 21:23:29 2023 +0100
chore(python-docs): improve getting started section
Signed-off-by: bossenti <bo...@posteo.de>
---
.../docs/getting-started/developing.md | 90 ++++++++++++++++++++++
.../docs/getting-started/first-steps.md | 68 ++++++++++++++++
.../docs/getting-started/installation.md | 43 -----------
streampipes-client-python/mkdocs.yml | 3 +-
4 files changed, 160 insertions(+), 44 deletions(-)
diff --git a/streampipes-client-python/docs/getting-started/developing.md b/streampipes-client-python/docs/getting-started/developing.md
new file mode 100644
index 000000000..7a62350b1
--- /dev/null
+++ b/streampipes-client-python/docs/getting-started/developing.md
@@ -0,0 +1,90 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ ~
+-->
+
+## 📖 Development Guide
+This document describes how to easily set up your local dev environment to work on the
+StreamPipes Python client 🐍.
+<br>
+
+### 🚀 First Steps
+
+1) **Set up your Python environment**
+
+Create a virtual Python environment with a tool of your choice.
+As a next step, install all required dependencies for the development, e.g., with `pip`:
+
+```bash
+pip install .[dev] # or alternatively: pip install .[all] to include dependencies for building the docs as well
+```
+
+In case you are on macOS and using `zsh` the following should work for you:
+```bash
+pip install ."[dev]"
+```
+<br>
+
+2) **Install pre-commit hook**
+
+The pre-commit hook is run before every commit and takes care about code style,
+linting, type hints, import sorting, etc. It will stop your commit in case the changes do not apply the expected format.
+Always check to have the recent version of the pre-commit hook installed otherwise the CI build might fail.
+If you are interested you can have a deeper look on the underlying library: [pre-commit](https://pre-commit.com/).
+
+```bash
+pre-commit install
+```
+The definition of the pre-commit hook can be found in [.pre-commit-config.yaml](.pre-commit-config.yaml).
+
+<br>
+
+### 👏 Conventions
+Below we list some conventions that we have agreed on for creating the StreamPipes Python client.
+Please comply to them when you plan to contribute to this project.
+If you have any other suggestions or would like to discuss them, we would be happy to hear from you on our mailing list [dev@streampipes.apache.org](mailto:dev@streampipes.apache.org).
+
+1) **Use `numpy` style for Python docstrings** 📄 <br>
+Please stick to the `numpy` style when writing docstrings, as we require this for generating our documentation.
+
+
+2) **Provide tests** ✅ <br>
+We are aiming for broad test coverage for the Python client and
+have therefore set a requirement of at least 90% unit test coverage.
+Therefore, please remember to write (unit) tests already during development.
+If you have problems with writing tests, don't hesitate to ask us for help directly in the PR or
+even before that via our mailing list (see above).
+
+
+<!---
+TODO: replace link to java file by link to documentation
+--->
+3) **Build a similar API as the Java client provides** 🔄 <br>
+Whenever possible, please try to develop the API of the Python library the same as the [Java client](../streampipes-client/src/main/java/org/apache/streampipes/client/StreamPipesClient.java) or Java SDK.
+By doing so, we would like to provide a consistent developer experience and the basis for automated testing in the future.
+
+---
+## 👨💻 Contributing
+*Before opening a pull request*, review the [Get Involved](https://streampipes.apache.org/getinvolved.html) page.
+It lists information that is required for contributing to StreamPipes.
+
+When you contribute code, you affirm that the contribution is your original work and that you
+license the work to the project under the project's open source license. Whether or not you
+state this explicitly, by submitting any copyrighted material via pull request, email, or
+other means you agree to license the material under the project's open source license and
+warrant that you have the legal authority to do so.
+
+---
\ No newline at end of file
diff --git a/streampipes-client-python/docs/getting-started/first-steps.md b/streampipes-client-python/docs/getting-started/first-steps.md
new file mode 100644
index 000000000..92975c39e
--- /dev/null
+++ b/streampipes-client-python/docs/getting-started/first-steps.md
@@ -0,0 +1,68 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one or more
+ ~ contributor license agreements. See the NOTICE file distributed with
+ ~ this work for additional information regarding copyright ownership.
+ ~ The ASF licenses this file to You under the Apache License, Version 2.0
+ ~ (the "License"); you may not use this file except in compliance with
+ ~ the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing, software
+ ~ distributed under the License is distributed on an "AS IS" BASIS,
+ ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ~ See the License for the specific language governing permissions and
+ ~ limitations under the License.
+ ~
+-->
+
+## 📚 Installation
+
+The StreamPipes Python library is meant to work with Python 3.8 and above. Installation can be done via `pip`:
+You can install the latest development version from GitHub, as so:
+
+```bash
+pip install streampipes
+# if you want to have the current development state you can also execute
+pip install git+https://github.com/apache/streampipes.git#subdirectory=streampipes-client-python
+```
+
+## ⬆️ Setting up StreamPipes
+When working with the StreamPipes Python library it is inevitable to have a running StreamPipes instance to connect and interact with.
+In case you don't have a running instance at hand, you can easily set up one on your local machine.
+Hereby you need to consider that StreamPipes supports different message broker (e.g., Kafka, NATS).
+Although the Python library aims to support all of them equally, we encourage you to run StreamPipes with the NATS protocol as the messaging layer.
+If you are using a different messaging broker and experience a problem, please do not hesitate to contact us.
+In case you are unsure if it is indeed a bug, please feel free to start a [discussion](https://github.com/apache/streampipes/discussions) on GitHub.
+Alternatively, file us a bug in form of a GitHub [issue](https://github.com/apache/streampipes/issues/new/choose).
+<br>
+The following shows how you can set up a StreamPipes instance that uses [NATS](https://docs.nats.io/) as messaging layer.
+
+### 🐳 Start StreamPipes via Docker Compose
+The easiest and therefore recommend way to get StreamPipes started is by using [docker compose](https://docs.docker.com/compose/).
+Therefore, you need Docker running. You can check if Docker is ready on your machine by executing.
+````bash
+docker ps
+````
+If this results in an output similar to the following, Docker is ready to continue.
+```
+CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+... ... ... ... ... ... ...
+```
+Otherwise, you need to start docker first.
+
+Please read the full guide on how to start StreamPipes with `docker compose` [here](https://github.com/apache/streampipes/blob/dev/installer/compose/README.md).
+So in our scenario, we will go with `docker-compose.nats.yml` to use NATS as messaging backend.
+Thereby, when running locally, we need to add the following port mapping entry to `nats.ports`:
+```yaml
+- 4222:4222
+```
+
+After this modification is applied, StreamPipes can simply be started with this command:
+```bash
+docker-compose -f docker-compose.nats.yml up -d
+```
+
+Once all services are started, you can access StreamPipes via `http://localhost`.
+
+Have fun discovering StreamPipes and our Python library 🚀
diff --git a/streampipes-client-python/docs/getting-started/installation.md b/streampipes-client-python/docs/getting-started/installation.md
deleted file mode 100644
index a5145d42a..000000000
--- a/streampipes-client-python/docs/getting-started/installation.md
+++ /dev/null
@@ -1,43 +0,0 @@
-<!--
- ~ Licensed to the Apache Software Foundation (ASF) under one or more
- ~ contributor license agreements. See the NOTICE file distributed with
- ~ this work for additional information regarding copyright ownership.
- ~ The ASF licenses this file to You under the Apache License, Version 2.0
- ~ (the "License"); you may not use this file except in compliance with
- ~ the License. You may obtain a copy of the License at
- ~
- ~ http://www.apache.org/licenses/LICENSE-2.0
- ~
- ~ Unless required by applicable law or agreed to in writing, software
- ~ distributed under the License is distributed on an "AS IS" BASIS,
- ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- ~ See the License for the specific language governing permissions and
- ~ limitations under the License.
- ~
--->
-
-# 📚 Installation
-
-The StreamPipes Python library is meant to work with Python 3.8 and above. Installation can be done via `pip`:
-You can install the latest development version from GitHub, as so:
-
-```bash
-pip install streampipes
-# if you want to have the current development state you can also execute
-pip install git+https://github.com/apache/streampipes.git#subdirectory=streampipes-client-python
-```
-
----
-# 👨💻 Contributing
-*Before opening a pull request*, review the [Get Involved](https://streampipes.apache.org/getinvolved.html) page.
-It lists information that is required for contributing to StreamPipes.
-
-When you contribute code, you affirm that the contribution is your original work and that you
-license the work to the project under the project's open source license. Whether or not you
-state this explicitly, by submitting any copyrighted material via pull request, email, or
-other means you agree to license the material under the project's open source license and
-warrant that you have the legal authority to do so.
-
-For more information on how to start with the Python client, click [here](https://github.com/apache/streampipes/blob/dev/streampipes-client-python/DEVELOPMENT.md).
-
----
\ No newline at end of file
diff --git a/streampipes-client-python/mkdocs.yml b/streampipes-client-python/mkdocs.yml
index edc04206a..e73ef072c 100644
--- a/streampipes-client-python/mkdocs.yml
+++ b/streampipes-client-python/mkdocs.yml
@@ -78,7 +78,8 @@ extra_css:
nav:
- Home: index.md
- Getting Started:
- - Installation: getting-started/installation.md
+ - First Steps: getting-started/first-steps.md
+ - Developing & Contributing: getting-started/developing.md
- Quickstart: getting-started/quickstart.md
- Examples:
- Introduction to the StreamPipes Python Client: examples/1-introduction-to-streampipes-python-client.ipynb