From 655e2adad1a382c21333147d281ce607d0d0fe22 Mon Sep 17 00:00:00 2001 From: Benjamin Braatz Date: Sun, 21 Mar 2021 23:39:16 +0100 Subject: [PATCH] Improve documentation. --- README.md | 10 ++- doc/index.md | 211 +++++++++++++++++++++++++++------------------------ 2 files changed, 119 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index 6b47681..57b530c 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,14 @@ messages between these plugins through a message bus. Documentation (in German) can be found at [doc/index.md](doc/index.md) in the source repository and at -[https://docs.graph-it.com/graphit/controlpi](https://docs.graph-it.com/graphit/controlpi). +[https://docs.graph-it.com/graphit/controlpi/](https://docs.graph-it.com/graphit/controlpi/). Code documentation (in English) including doctests is contained in the source files. +An API documentation generated by pdoc3 can be found at +[doc/controlpi/index.html](doc/controlpi/index.html) in the source +repository and at +[https://docs.graph-it.com/graphit/controlpi/controlpi/](https://docs.graph-it.com/graphit/controlpi/controlpi/). +API documentation for the bundled collection of plugins can be found at +[doc/controlpi_plugins/index.html](doc/controlpi_plugins/index.html) in the source +repository and at +[https://docs.graph-it.com/graphit/controlpi/controlpi_plugins/](https://docs.graph-it.com/graphit/controlpi/controlpi_plugins/). diff --git a/doc/index.md b/doc/index.md index 0a5cf05..e99e8ba 100644 --- a/doc/index.md +++ b/doc/index.md @@ -9,97 +9,14 @@ Dieses Paket enthält die grundlegende Infrastruktur für ein ControlPi-System, die Plugins verwaltet und ihnen ermöglicht über einen Bus Nachrichten auszutauschen. -## Installation zum Entwickeln -Es wird mindestens Python 3.7 benötigt. Für Ubuntu-Versionen, die selbst -noch keine aktuelle Python-Version zur Verfügung stellen, kann eine aus dem -PPA [deadsnakes](https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa) -installiert werden: -```sh -$ sudo add-apt-repository ppa:deadsnakes/ppa -$ sudo apt update -$ sudo apt install python3.9 python3.9-venv -``` - -Das Repository mit dem Code dieses Pakets kann vom öffentlichen git-Server -bezogen werden: -```sh -$ git clone git://git.graph-it.com/graphit/controlpi.git -``` -(Falls Zugang zu diesem Server per SSH besteht und Änderungen gepusht -werden sollen, sollte stattdessen die SSH-URL benutzt werden.) - -Damit Python-Module in diesem Paket gefunden und eventuelle Abhängigkeiten -installiert werden, dies aber von anderen Teilen des Systems, auf dem -entwickelt wird, isoliert gehalten wird, sollte ein virtuelles Environment -verwendet werden. Wo dieses Verzeichnis liegt, ist dabei relativ egal. -Übliche Orte sind innerhalb des Code-Repository-Verzeichnisses (hierfür -wird `venv/` von git ignoriert), parallel zum Code-Repository oder an einer -zentralen Stelle des Home-Verzeichnisses gesammelt. - -Sobald das virtuelle Environment eingerichtet und aktiviert ist, beziehen -sich Befehle wie `python` und `pip` auf die in diesem Environment -konfigurierten und müssen nicht mehr mit genauer Version aufgerufen werden: -```sh -$ python3.9 -m venv -$ source /bin/activate -(venv)$ pip install --upgrade pip setuptools wheel -``` - -Damit Änderungen am Code sofort wirksam werden und getestet werden können, -sollte das Paket, an dem gerade entwickelt wird, im virtuellen Environment -editierbar installiert werden: -```sh -(venv)$ pip install --editable -``` - -## Code-Stil, Typ-Checks und Tests -Die Formatierung des Codes und das Vorhandensein und der Stil der -Kommentare werden durch `pycodestyle` und `pydocstyle` überprüft. Die an -Funktionen und Variablen annotierten Typ-Informationen werden durch `mypy` -gecheckt. Alle drei Tools können rekursiv ein gesamtes Python-Paket -überprüfen: -```sh -(venv)$ pycodestyle /controlpi -(venv)$ pydocstyle /controlpi -(venv)$ mypy /controlpi -``` - -Sie sind als Extra-Requirements in der Datei `setup.py` definiert, sodass -sie mit einem einzigen `pip`-Aufruf installiert werden können: -```sh -(venv)$ pip install --editable [dev] -``` - -Der Code wird durch in die Dokumentation eingebettete „doctests“ getestet. -Diese können für jede Code-Datei einzeln mit dem in der -Python-Standard-Distribution enthaltenen Modul `doctest` ausgeführt werden: -```sh -(venv)$ python -m doctest -``` -(Für die Datei `__main__.py`, die das kleine Hauptprogramm zum Ausführen -des Systems enthält, funtioniert dies leider nicht.) - -Komplette Informationen über alle durchgeführten Tests und die Abdeckung -des Codes mit Tests erhält man mit der zusätzlichen Option `-v`: -```sh -(venv)$ python -m doctest -v -``` - -Außerdem wird durch die `[dev]`-Extras in `setup.py` auch das Tool `pdoc` -zur automatischen Generierung von API-Dokumentation in HTML installiert: -```sh -(venv)$ pdoc --html --config sort_identifiers=False --force \ - --output-dir doc/ controlpi/ controlpi-plugins/ -``` - ## Überblick Die ControlPi-Infrastruktur hat zwei Haupt-Bestandteile: - Ein Plugin-System erlaubt es, ohne Anpassungen am Code der Infrastruktur weitere Plugin-Klassen in Python zu implementieren und (in anderen Code-Repositories und anderen Distributions-Paketen) zum System hinzuzufügen. - Im Modul `controlpi-plugins.util` bzw. der Datei - `controlpi-plugins/util.py` befindet sich eine Reihe nützlicher + In den Modulen `controlpi_plugins.util`, `controlpi_plugins.state` und + `controlpi_plugins.wait` befinden sich eine Reihe nützlicher Standard-Plugins, an denen die generelle Struktur nachvollzogen werden kann. - Ein Nachrichten-Bus erlaubt den Austausch von Nachrichten zwischen allen @@ -107,6 +24,11 @@ Die ControlPi-Infrastruktur hat zwei Haupt-Bestandteile: Nachrichten bestehen aus einer Menge von Schlüssel-Wert-Paaren. (Sie sind Dictionaries bzw. Mappings.) +Die generierte Dokumentation des API der grundlegenden Infrastruktur ist +unter [controlpi/](graphit/controlpi/controlpi/) zu finden. +Die Kollektion an grundlegenden Plugins ist unter +[controlpi_plugins/](graphit/controlpi/controlpi_plugins/) dokumentiert. + Um Nachrichten zu senden und/oder zu empfangen muss ein Klient am Bus unter einem Namen registriert werden. Eine Plugin-Instanz kann entweder genau einen Klienten registrieren (der @@ -116,7 +38,7 @@ verbundene Geräte oder die gerade offenen Verbindungen einer Netzwerk-Schnittstelle. Die Infrastruktur definiert nur die Anforderung, dass jede gesendete -Nachricht einen speziellen Schlüssel `'sender'` mit dem Namen des sendenden +Nachricht einen speziellen Schlüssel `"sender"` mit dem Namen des sendenden Klienten als Wert enthält. Der Bus überprüft, ob diese Art von Nachricht für diesen Sender registriert wurde, und liefert sie nur dann aus. @@ -126,38 +48,38 @@ Nachrichten. Sie müssen nicht unbedingt bestimmte Empfänger haben, sie gehören nicht unbedingt zu einem bestimmten Typen etc. -Einige Konventionen, die z.B. von den Plugins in `controlpi-plugins.util` +Einige Konventionen, die z.B. von den Plugins in diesem Repository eingehalten werden, sind aber: - Einige Nachrichten signalisieren, dass ein Ereignis eingetreten ist. - Sie haben in der Regel einen Schlüssel `'event'` mit einem Wert, der die + Sie haben in der Regel einen Schlüssel `"event"` mit einem Wert, der die Art des Ereignisses passend benennt und eventuell weitere Schlüssel, die dieses näher beschreiben. Auch das Registrieren und Deregistrieren von Klienten am Bus selbst wird - als Ereignis mit einem `'event'`-Schlüssel signalisiert. + als Ereignis mit einem `"event"`-Schlüssel signalisiert. - Einige Nachrichten sind als Kommandos an einen bestimmten Klienten gedacht. - Sie haben in der Regel einen Schlüssel `'target'` mit dem Namen dieses - Ziel-Klienten als Wert und einen Schlüssel `'command'` mit einem + Sie haben in der Regel einen Schlüssel `"target"` mit dem Namen dieses + Ziel-Klienten als Wert und einen Schlüssel `"command"` mit einem festgelegten Namen für das auszuführende Kommando und eventuell weiteren Schlüsseln, die dann so etwas wie Parameter des Kommandos sind. (Es können aber auch andere Klienten, beispielsweise Logger oder Debug-Oberflächen, diese Nachrichten empfangen und verarbeiten, da - `'target'`-Schlüssel von der Infrastruktur bzw. dem Bus nicht speziell + `"target"`-Schlüssel von der Infrastruktur bzw. dem Bus nicht speziell behandelt werden.) - Das `State`-Plugin ist ein Beispiel, welche Nachrichten (Boolesche) Zustände senden und empfangen sollten: - Bei Änderung des Zustandes wird ein Ereignis mit `'event'`-Wert - `'changed'` und dem neuen Zustand als `'state'`-Wert geschickt. - Das Plugin reagiert auf ein `'get state'`-Kommando, indem es eine - Nachricht mit dem Schlüssel `'state'` und dem aktuellen Zustand als Wert - (aber ohne `'event'`-Schlüssel schickt, da kein wirkliches Ereignis + Bei Änderung des Zustandes wird ein Ereignis mit `"event"`-Wert + `"changed"` und dem neuen Zustand als `"state"`-Wert geschickt. + Das Plugin reagiert auf ein `"get state"`-Kommando, indem es eine + Nachricht mit dem Schlüssel `"state"` und dem aktuellen Zustand als Wert + (aber ohne `"event"`-Schlüssel schickt, da kein wirkliches Ereignis eingetreten ist) schickt. Da in diesem Plugin der Zustand auch von außen setzbar ist, reagiert es - auf ein `'set state'`-Kommando, das einen `'new state'`-Schlüssel mit + auf ein `"set state"`-Kommando, das einen `"new state"`-Schlüssel mit einem neuen, zu setzenden Wert enthält, indem es diesen Zustand setzt (und eine Ereignis-Nachricht sendet, wenn dies eine Änderung war). - Sowohl der Bus selbst als auch das `State`-Plugin senden als Reaktion auf - `'get …'`-Nachrichten Antworten, die genau so aufgebaut sind wie die + `"get …"`-Nachrichten Antworten, die genau so aufgebaut sind wie die Ereignis-Nachrichten, die sie auch aktiv senden, wenn eine Änderung eingetreten ist. Hierdurch können Klienten diese Nachrichten gleich behandeln, wenn das @@ -173,7 +95,7 @@ sich nicht darauf verlassen, die einzigen zu sein, die auf eine Nachricht reagieren. Die ControlPi-Infrastruktur ist auf nebenläufiger Programmierung mit -`asyncio` aufgebaut. +[`asyncio`](https://docs.python.org/3/library/asyncio.html) aufgebaut. Diese garantiert, dass Code solange ohne Unterbrechung läuft, bis er selbst die Kontrolle abgibt, weil er auf eine Ein- oder Ausgabe-Operation oder ähnliches wartet. @@ -459,7 +381,7 @@ Dies wiederholt sich jetzt solange weiter, bis das Programm abgebrochen wird. ## Installation auf Raspberry Pi -Auch auf dem Raspberry Pi wollen wir den Code in ein virtuelles Environment +Auf dem Raspberry Pi wollen wir den Code in ein virtuelles Environment installieren, wobei die weitere Vorgehensweise davon ausgeht, dass dieses direkt unter `/home/pi` liegt, also insgesamt den Pfad `/home/pi/controlpi-venv` hat: @@ -506,3 +428,90 @@ Die Ausgaben können dann im Journal nachvollzogen werden: ```sh $ journalctl -u controlpi.service ``` + +## Installation zum Entwickeln +Es wird mindestens Python 3.7 benötigt. +```sh +$ sudo apt install python3 python3-venv +``` + +Das Repository mit dem Code dieses Pakets kann vom öffentlichen git-Server +bezogen werden: +```sh +$ git clone git://git.graph-it.com/graphit/controlpi.git +``` +(Falls Zugang zu diesem Server per SSH besteht und Änderungen gepusht +werden sollen, sollte stattdessen die SSH-URL benutzt werden.) + +Damit Python-Module in diesem Paket gefunden und eventuelle Abhängigkeiten +installiert werden, dies aber von anderen Teilen des Systems, auf dem +entwickelt wird, isoliert gehalten wird, sollte ein virtuelles Environment +verwendet werden. Wo dieses Verzeichnis liegt, ist dabei relativ egal. +Übliche Orte sind innerhalb des Code-Repository-Verzeichnisses (hierfür +wird `venv/` von git ignoriert), parallel zum Code-Repository oder an einer +zentralen Stelle des Home-Verzeichnisses gesammelt. + +Sobald das virtuelle Environment eingerichtet und aktiviert ist, beziehen +sich Befehle wie `python` und `pip` auf die in diesem Environment +konfigurierten und müssen nicht mehr mit genauer Version aufgerufen werden: +```sh +$ python3 -m venv +$ source /bin/activate +(venv)$ pip install --upgrade pip setuptools wheel +``` + +Damit Änderungen am Code sofort wirksam werden und getestet werden können, +sollte das Paket, an dem gerade entwickelt wird, im virtuellen Environment +editierbar installiert werden: +```sh +(venv)$ pip install --editable +``` + +## Code-Stil, Typ-Checks und Tests +Die Formatierung des Codes und das Vorhandensein und der Stil der +Kommentare werden durch +[`pycodestyle`](https://pycodestyle.pycqa.org/en/latest/) und +[`pydocstyle`](http://www.pydocstyle.org/en/stable/) überprüft. +Die an Funktionen und Variablen annotierten Typ-Informationen werden durch +[`mypy`](http://mypy-lang.org/) gecheckt. +Alle drei Tools können rekursiv ein gesamtes Python-Paket überprüfen: +```sh +(venv)$ pycodestyle /controlpi +(venv)$ pydocstyle /controlpi +(venv)$ mypy /controlpi +``` + +Sie sind als Extra-Requirements in der Datei `setup.py` definiert, sodass +sie mit einem einzigen `pip`-Aufruf installiert werden können: +```sh +(venv)$ pip install --editable [dev] +``` + +Der Code wird durch in die Dokumentation eingebettete „doctests“ getestet. +Diese können für jede Code-Datei einzeln mit dem in der +Python-Standard-Distribution enthaltenen Modul +[`doctest`](https://docs.python.org/3/library/doctest.html) ausgeführt +werden: +```sh +(venv)$ python -m doctest +``` +(Für die Datei `__main__.py`, die das kleine Hauptprogramm zum Ausführen +des Systems enthält, funtioniert dies leider nicht.) + +Komplette Informationen über alle durchgeführten Tests und die Abdeckung +des Codes mit Tests erhält man mit der zusätzlichen Option `-v`: +```sh +(venv)$ python -m doctest -v +``` + +Außerdem wird durch die `[dev]`-Extras in `setup.py` auch das Tool +[`pdoc`](https://pdoc3.github.io/pdoc/) zur automatischen Generierung von +API-Dokumentation in HTML installiert: +```sh +(venv)$ pdoc --html --config sort_identifiers=False --force \ + --output-dir doc/ controlpi/ controlpi_plugins/ +``` +Mit diesem wurden auch die oben verlinkten API-Dokumentationen für +[`controlpi`](graphit/controlpi/controlpi/) und +[`controlpi_plugins`](graphit/controlpi/controlpi_plugins/) +generiert. -- 2.34.1