This is an automated email from the ASF dual-hosted git repository.
bossenti pushed a commit to branch dev
in repository https://gitbox.apache.org/repos/asf/streampipes.git
The following commit(s) were added to refs/heads/dev by this push:
new 5653e5e60 chore(python-docs): improve getting started section (#1310)
5653e5e60 is described below
commit 5653e5e604ac358f9f9fc53a339dae52995cd7d2
Author: Tim <[email protected]>
AuthorDate: Wed Feb 22 07:33:04 2023 +0100
chore(python-docs): improve getting started section (#1310)
* chore(python-docs): improve getting started section
Signed-off-by: bossenti <[email protected]>
* chore(python-docs): fixing yaml path
* chore(python-docs): add roadmap section
Signed-off-by: bossenti <[email protected]>
---------
Signed-off-by: bossenti <[email protected]>
---
.../docs/getting-started/developing.md | 106 +++++++++++++++++++++
.../docs/getting-started/first-steps.md | 68 +++++++++++++
.../docs/getting-started/installation.md | 43 ---------
streampipes-client-python/mkdocs.yml | 3 +-
4 files changed, 176 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..a84fa203b
--- /dev/null
+++ b/streampipes-client-python/docs/getting-started/developing.md
@@ -0,0 +1,106 @@
+<!--
+ ~ 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
[[email protected]](mailto:[email protected]).
+
+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.
+
+---
+## 🚀 Roadmap
+
+Broadly speaking, we plan to expand or add new aspects/functionality to the
library where we are focusing on the following:
+
+- increase coverage of StreamPipes API 🔗
+- build a comprehensive function zoo 🐘
+- support more messaging broker 📬
+- possibility to build pipeline elements 🔧
+
+In case you want to have a more detailed look on what we are currently
planning, have a look at our [open
issues](https://github.com/apache/streampipes/labels/python)(more short-term
driven).
+
+Of course, contributions are always highly appreciated 🔮
+
+Stay tuned!
+
+---
+## 👨💻 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..a416dce35
--- /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 `services.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
