docs: some simple documentation

.github/workflow/build_docs.yml

@@ -0,0 +1,48 @@
+name: Deploy static content to Pages
+
+on:
+  push:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Configure python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Configure poetry
+        uses: abatilo/actions-poetry@v2
+        with:
+          poetry-version: 1.5.1S
+      - name: Build docs
+        run: |
+          poetry update --with docs
+          poetry run mkdocs build
+          poetry run pdoc --html swarm -o site
+          mv site/swarm site/reference
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: 'site'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflow/deploy_to_pypi.yml

@@ -0,0 +1,17 @@
+name: Build and publish python package
+
+on:
+  release:
+    types: [ published ]
+
+jobs:
+  publish-service-client-package:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Publish PyPi package
+        uses: code-specialist/pypi-poetry-publish@v1
+        with:
+          ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PUBLISH_REGISTRY_PASSWORD: ${{ secrets.PYPI_TOKEN }}

docs/index.md

@@ -0,0 +1,25 @@
+# The ftSwarm Project
+
+The goal of the ftSwarm project is to build small networked controllers for DIY and toy applications. Since they are
+networked with each other, they can act like a swarm. For example, they can act as several independent robots to solve a
+task together. In larger models, the controllers can be installed at different positions close to actuators and
+sensors - together they control the complete model.
+
+Originally, the project was designed to use with fischertechnik. Since the mounting grooves are compatible with
+Makerbeam profiles, ftSwarms could be used in many DIY projects.
+Although the ftSwam is as small as a matchbox with only 45.0 x 37.5 x 17 mm, it can control two 9V DV motors, up to 16
+RGB LEDs, one servo and read out 4 analog or digital sensors.
+As a control panel, the ftSwarmControl has, in addition to 2 joysticks, 8 buttons and an LCD display, the ability to
+control 2 DC motors and read 4 digital sensors.
+
+## Getting the Hardware
+
+Since building this hardware on your own is a little bit tricky, we offer ready to use devices at
+[gundermann-software.de](https://gundermann-software.de). For all who wants to build their own pcb, we provide the needed schematic files at github as
+well.
+
+## Other Documentation
+
+The main documentation is located at [ftswarm.de](http://ftswarm.de), this is only some temporary documentation for the
+python library. Most functions and classes are named like the corresponding C++ library, so you can use the C++
+documentation as well.

docs/quickstart.md

@@ -0,0 +1,90 @@
+# Quickstart
+
+If you already got the hardware with the newest firmware, you're already
+done with the c++ part. Just connect the ftSwarm to your computer and
+install the python library:
+
+```bash
+pip install ftswarm.py
+```
+
+If you want to build the firmware on your own, you can find the source
+code at [github](https://github.com/elektrofuzzis/ftSwarm).
+
+## Getting Started
+
+After building a swarm and connecting one of the ftSwarm devices to your
+computer, you can start to control it with python. First, you have to
+import the library and create a swarm object as well as get asyncio running:
+
+```python
+import swarm
+import asyncio
+
+
+async def main():
+    ftswarm = swarm.FtSwarm(port="/dev/ttyUSB0")  # or "COM1" (or similar) on windows
+    # do something with the ftSwarm
+
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+The port has to be set to the serial port where the ftSwarm is connected.
+If you use windows, you can find the port in the device manager.
+
+## About aliases
+
+A swarm can become quite complex fast. To make it easier to
+control the hardware, you can use aliases. An alias is a name for a
+specific hardware. For example, you can create an alias for the first
+motor in the cli. More information on this topic can be found in the
+[official config documentation](https://ftswarm.elektrofuzzis.dev/de/advanced/Configuration/).
+
+All IO Ports can be called by their alias name or their controller hostname + number, e.g. "ftswarm1.A1" or "
+ftswarm1.M2".
+
+Now you can finally control some hardware.
+
+## Example: Reading a switch
+
+For this example, we will read the state of a switch. The switch is
+connected to a digital input called `myswitch`.
+
+```python
+import swarm
+import asyncio
+
+async def main():
+    ftswarm = swarm.FtSwarm(port="/dev/ttyUSB0")  # Enter your port here
+    switch = await ftswarm.get_switch("myswitch")
+    while True:
+        print("Switch state:", await switch.get_state())
+        await asyncio.sleep(1)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```
+
+## Example: Writing to a motor
+
+For this example, we will write a value to a motor. The motor is
+connected to a digital output called `mymotor`.
+
+```python
+import swarm
+import asyncio
+
+async def main():
+    ftswarm = swarm.FtSwarm(port="/dev/ttyUSB0")  # Enter your port here
+    motor = await ftswarm.get_motor("mymotor")
+    while True:
+        await motor.set_speed(255)
+        await asyncio.sleep(1)
+        await motor.set_speed(-255)
+        await asyncio.sleep(1)
+
+if __name__ == '__main__':
+    asyncio.run(main())
+```

mkdocs.yml

@@ -0,0 +1,12 @@
+site_name: ftSwarm.py - Help and Reference
+copyright: "© Christian Bergschneider & Stefan Fuss"
+site_url: https://ftswarm-py.bloeckchengrafik.de
+
+theme:
+  name: material
+
+nav:
+  - Introduction: 'index.md'
+  - 'quickstart.md'
+  - Reference: '/reference'
+  - 'Issue Tracker': 'https://github.com/Bloeckchengrafik/ftswarm.py'