Add bindings to mkdocs

.github/workflows/publish.yml

@@ -43,3 +43,4 @@ jobs:
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
+          packages-dir: src/bindings/python/dist/

build-scripts/build-bindings.sh

@@ -11,13 +11,15 @@ VERSION="$(meson introspect --projectinfo builddir | jq -r '.version')"
 function python() {
     # Package python bindings
     PYTHON_BINDINGS_DIR="src/bindings/python/"
+    cd $PYTHON_BINDINGS_DIR
+
     ## Set version and release
     sed \
         -e "s|@VERSION@|${VERSION}|g" \
-        < $PYTHON_BINDINGS_DIR"setup.py.in" \
-        > $PYTHON_BINDINGS_DIR"setup.py"
-        
-    python3 $PYTHON_BINDINGS_DIR"setup.py" bdist_wheel --dist-dir=dist/
+        < "setup.py.in" \
+        > "setup.py"
+
+    python3 "setup.py" bdist_wheel --dist-dir=dist/
 }
 
 echo "Building bindings $1"

doc/docs/api/bindings.md

@@ -0,0 +1,74 @@
+<!-- markdownlint-disable-file MD041 -->
+# D-Bus API bindings
+
+Hirte provides for its public API
+[introspection data](https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) in the
+[data directory](https://github.com/containers/hirte/tree/main/data). These XML files can be used as input to code
+generation tools to create clients for using the described D-Bus API in various programming languages.
+For example:
+
+- `C`: [gdbus-codegen](https://developer-old.gnome.org/gio/stable/gdbus-codegen.html)
+- `Go`: [dbus-codegen-go](https://github.com/amenzhinsky/dbus-codegen-go)
+- `Rust`: [dbus-codegen-rust](https://crates.io/crates/dbus-codegen)
+- and many more
+
+## pyhirte
+
+For `python`, the dynamically generated proxies (e.g. from [dasbus](https://github.com/rhinstaller/dasbus)) don't
+require such a generation and work well on their own. These proxies, however, don't provide type hints. Because of that
+the hirte project provides `pyhirte` - auto-generated, typed python bindings.
+
+### Installation
+
+Install `pyhirte` via:
+
+```bash
+# from rpm package
+dnf install python3-pyhirte
+
+# or from PyPI
+pip install pyhirte
+```
+
+### Usage
+
+The following code snippets showcase how `pyhirte` can be used:
+
+```python
+# starting a systemd unit
+--8<-- "pyhirte-examples/StartUnit:5"
+
+# and stopping it again
+--8<-- "pyhirte-examples/StopUnit:7"
+```
+
+```python
+# enabling a systemd unit to be executed on startup
+--8<-- "pyhirte-examples/EnableUnit:5"
+
+# and disabling it again
+--8<-- "pyhirte-examples/DisableUnit:7"
+```
+
+```python
+# listing all nodes
+--8<-- "pyhirte-examples/ListAllNodes:5"
+```
+
+```python
+# listing all units on all nodes
+--8<-- "pyhirte-examples/ListNodeUnits:5"
+
+
+# or easily filter them and only display active services
+--8<-- "pyhirte-examples/ListActiveServices:5"
+```
+
+```python
+# getting properties from systemd units
+# e.g. the CPUWeight
+--8<-- "pyhirte-examples/CPUWeight:5"
+
+# and setting values for them
+--8<-- "pyhirte-examples/SetCPUWeight:5"
+```

doc/docs/getting_started.md

@@ -5,9 +5,13 @@
 
 On Fedora systems, hirte can be directly installed from the Fedora repository.
 On CentOS-Stream systems, it can be installed using the COPR repository shipping
-the latest hirte code. That repository can be enabled using: dnf copr enable
-mperina/hirte-snapshot centos-stream-9.  This should no longer be necessary once
-hirte is made available in EPEL.
+the latest hirte code. That repository can be enabled using:
+
+```bash
+dnf copr enable mperina/hirte-snapshot centos-stream-9
+```
+
+This should no longer be necessary once hirte is made available in EPEL.
 
 On the laptop install both hirte and the hirte-agent via this command:
 

doc/mkdocs.yml

@@ -12,6 +12,7 @@ nav:
   - DBus API: 
     - Description: api/description.md
     - Examples: api/examples.md
+    - Bindings: api/bindings.md
   - Proxy Services: proxy_services.md
   - MAN Pages:
     - Binaries:

src/bindings/README.md

@@ -8,4 +8,3 @@ functions are written to simplify recurring tasks.
 
 - [bindings/generator](./generator/): small python project used to generate client code for the D-Bus API
 - [bindinds/python](./python/): python client for hirte
-- [bindings/examples](./examples/): contains example code for using the bindings

src/bindings/python/setup.py

@@ -12,6 +12,7 @@ def readme():
     version="0.4.0",
     description="Python bindings for hirte's D-Bus API",
     long_description=readme(),
+    long_description_content_type="text/markdown",
     author="Hirte developers",
     url="https://github.com/containers/hirte/",
     license="LGPL-2.0-or-later",

src/bindings/python/setup.py.in

@@ -12,6 +12,7 @@ setup(
     version="@VERSION@",
     description="Python bindings for hirte's D-Bus API",
     long_description=readme(),
+    long_description_content_type="text/markdown",
     author="Hirte developers",
     url="https://github.com/containers/hirte/",
     license="LGPL-2.0-or-later",