Merge pull request #313 from BlackLight/snyk-upgrade-58f5a7acf019c661bec911d06f0bf10a

[Snyk] Upgrade core-js from 3.21.1 to 3.23.4

.gitignore

@@ -19,3 +19,6 @@ platypush/requests
 /http-client.env.json
 /platypush/backend/http/static/css/dist
 /tests/etc/dashboards
+.coverage
+coverage.xml
+Session.vim

.gitlab-ci.yml

@@ -0,0 +1,72 @@
+sync-to-github:
+  stage: build
+  script:
+    - echo "Synchronizing repo state to Github"
+    - export REPO_DIR="$(mktemp -d /tmp/platypush-XXXXX)"
+    - git clone git@git.platypush.tech:platypush/platypush.git "$REPO_DIR"
+    - cd "$REPO_DIR"
+    - git remote add github git@github.com:/BlackLight/platypush.git
+    - git checkout $CI_COMMIT_BRANCH
+    - git pull
+    - git push --mirror -v github
+
+run-tests:
+  stage: test
+  script:
+    - ./.gitlab/run_ci_tests.sh
+
+rebuild-docs:
+  stage: deploy
+  only:
+    - master
+  script:
+    - ./.gitlab/rebuild_docs.sh
+
+update-aur-packages:
+  stage: deploy
+  only:
+    - master
+    - tags
+  script:
+    - echo "Updating AUR packages"
+    - export REPO_DIR="$(mktemp -d /tmp/platypush-distutils-XXXXX)"
+    - git clone git@fabiomanganiello.com:/home/git/platypush-distutils.git "$REPO_DIR"
+    - cd "$REPO_DIR"
+    - git submodule init
+    - git submodule update
+    - cd distro/arch/git
+    - git checkout master
+    - git pull --rebase
+    - cd ../../../
+    - cd distro/arch/stable
+    - git checkout master
+    - git pull --rebase
+    - cd ../../../
+    - ./update.sh
+    - cd distro/arch/git
+    - changes="$(git status --porcelain --untracked-files=no)"
+    - "[[ -n \"$changes\" ]] && git commit -a -m '[Automatic] Package updated' && git push || echo 'No changes'"
+    - cd ../../../
+    - cd distro/arch/stable
+    - changes="$(git status --porcelain --untracked-files=no)"
+    - "[[ -n \"$changes\" ]] && git commit -a -m '[Automatic] Package updated' && git push || echo 'No changes'"
+
+upload-pip-package:
+  stage: deploy
+  only:
+    - tags
+  script:
+    # Update the CI/CD configuration
+    - cd ~/platypush-ci-cd
+    - git pull
+    - cd -
+    # Build the package
+    - rm -rf build dist *.egg-info
+    - export VERSION=$(grep -e '^\s*__version__\s*=' platypush/__init__.py | sed -r -e 's/^\s*__version__\s*=\s*.(.+?).\s*$/\1/')
+    - source ~/.credentials/pypi.env
+    - python setup.py sdist bdist_wheel
+    # Upload to PyPI
+    - twine upload --repository platypush ./dist/platypush-${VERSION}.tar.gz
+    # Upload to the local package repository
+    - TWINE_USERNAME=$LOCAL_TWINE_USERNAME TWINE_PASSWORD=$LOCAL_TWINE_PASSWORD twine upload --repository-url https://git.platypush.tech/api/v4/projects/3/packages/pypi dist/platypush-${VERSION}.tar.gz
+

.gitlab/rebuild_docs.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+
+LOGFILE="./docs.log"
+STATUS_IMG_PATH="./docs-status.svg"
+
+build_docs() {
+    cd ./docs || exit 1
+    make html 2>&1 | tee "../$LOGFILE"
+    ret=$?
+    cd .. || exit 1
+    return $?
+}
+
+########
+# MAIN #
+########
+
+build_docs
+ret=$?
+
+log_base_path="$(date +/opt/tests/platypush/logs/docs/%Y-%m-%dT%H:%M:%S.%m)"
+if [[ $ret == 0 ]]; then
+    wget -O "$STATUS_IMG_PATH" https://ci.platypush.tech/docs/passed.svg
+    cp "$LOGFILE" "${log_base_path}_PASSED.log"
+else
+    wget -O "$STATUS_IMG_PATH" https://ci.platypush.tech/docs/failed.svg
+    cp "$LOGFILE" "${log_base_path}_FAILED.log"
+fi
+
+mv "$STATUS_IMG_PATH" /opt/tests/platypush/logs/docs/
+mv "$LOGFILE" /opt/tests/platypush/logs/latest.log
+cp -r docs/build/html /opt/repos/platypush/docs/build/
+exit $ret

.gitlab/run_ci_tests.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+
+BASE_DIR="$(mktemp -d '/tmp/platypush-ci-tests-XXXXX')"
+VENV_DIR="$BASE_DIR/venv"
+TEST_LOG="./test.log"
+STATUS_IMG_PATH="./status.svg"
+
+cleanup() {
+    echo "Cleaning up environment"
+    rm -rf "$BASE_DIR"
+}
+
+prepare_venv() {
+    echo "Preparing virtual environment"
+    python -m venv "$VENV_DIR"
+    cd "$VENV_DIR" || exit 1
+    source ./bin/activate
+    cd - || exit 1
+}
+
+install_repo() {
+    echo "Installing latest version of the repository"
+    pip install '.[http]'
+}
+
+run_tests() {
+    echo "Running tests"
+    pytest 2>&1 | tee "$TEST_LOG"
+    deactivate
+
+    if grep -e '^FAILED ' "$TEST_LOG"; then
+      return 2
+    fi
+
+    return 0  # PASSED
+}
+
+########
+# MAIN #
+########
+
+cleanup
+prepare_venv
+install_repo
+run_tests
+ret=$?
+cleanup
+
+log_base_path="$(date +/opt/tests/platypush/logs/%Y-%m-%dT%H:%M:%S.%m)"
+if [[ $ret == 0 ]]; then
+    wget -O "$STATUS_IMG_PATH" https://ci.platypush.tech/passed.svg
+    cp "$TEST_LOG" "${log_base_path}_PASSED.log"
+else
+    wget -O "$STATUS_IMG_PATH" https://ci.platypush.tech/failed.svg
+    cp "$TEST_LOG" "${log_base_path}_FAILED.log"
+fi
+
+mv "$STATUS_IMG_PATH" /opt/tests/platypush/logs/status.svg
+mv "$TEST_LOG" /opt/tests/platypush/logs/latest.log
+exit $ret

.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.1.0
+    hooks:
+    # -   id: trailing-whitespace
+    # -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: check-json
+    -   id: check-xml
+    -   id: check-symlinks
+    -   id: check-added-large-files
+
+-   repo: https://github.com/Lucas-C/pre-commit-hooks-nodejs
+    rev: v1.1.2
+    hooks:
+    -   id: markdown-toc
+
+- repo: https://github.com/pycqa/flake8
+  rev: 4.0.1
+  hooks:
+    - id: flake8
+      additional_dependencies:
+        - flake8-bugbear
+        - flake8-comprehensions
+        - flake8-simplify
+
+-   repo: https://github.com/psf/black
+    rev: 22.3.0
+    hooks:
+    -   id: black

CHANGELOG.md

@@ -5,6 +5,286 @@ Given the high speed of development in the first phase, changes are being report
 
 ## [Unreleased]
 
+- Removed `clipboard` backend. Enabling the `clipboard` plugin will also enable
+  clipboard monitoring, with no need for an additional backend.
+
+## [0.23.3] - 2022-06-01
+
+### Added
+
+- Added `ntfy` integration (see #219).
+- Support for a default `config.yaml` if one isn't specified in the default
+  locations.
+
+### Changed
+
+- The HTTP server dependencies are now marked as required, since the default
+  `config.yaml` will have the HTTP backend enabled by default in order to allow
+  the creation of a first user.
+- Updated Vue.js frontend dependencies to the latest version.
+- Removed bulma from the frontend dependencies, making the frontend much
+  lighter and loading times much faster.
+- Other UI improvements.
+
+### Fixed
+
+- More reliable cronjobs in case of DST change or any clock changes in general
+  (see #217).
+- Fixed `--redis-queue` argument.
+
+## [0.23.2] - 2022-03-27
+
+### Added
+
+- Support for asynchronous events over GPIO PINs. It is now possible to specify
+  a list of `monitored_pins` in the [`gpio`
+  plugin](https://git.platypush.tech/platypush/platypush/-/blob/master/platypush/plugins/gpio/__init__.py)
+  configuration. A change in the value on those GPIO PINs (caused by e.g. a
+  button, a binary sensor or a probe) will trigger a
+  `platypush.message.event.gpio.GPIOEvent` that you can use in your automation
+  scripts.
+
+- Simplified script API to interact with platform variables
+  (closes [#206](https://git.platypush.tech/platypush/platypush/-/issues/206)).
+  You can now read and write stored variables in your Platypush scripts through
+  a much more intuitive interface compared to explicitly using the `variable`
+  plugin explicitly:
+
+```python
+from platypush.context import Variable
+
+# ...
+
+my_var = Variable.get('my_var')
+my_var = int(my_var) + 1
+Variable.set(my_var=my_var)
+```
+
+## [0.23.0] - 2022-03-01
+
+### Added
+
+- Added [Jellyfin integration](https://git.platypush.tech/platypush/platypush/-/issues/208).
+
+### Fixed
+
+- Merged several PRs from `dependabot`.
+
+- Fixed management of the `CN` field in the `calendar.ical` plugin.
+
+## [0.22.10] - 2022-02-07
+
+### Added
+
+- Refactored the `dbus` integration. The plugin and backend have been merged into a
+  single plugin component, and the ability to subscribe to custom signals has been
+  added.
+
+### Fixed
+
+- Proper support for empty payloads on the integrations that trigger a `SensorDataChangeEvent`.
+- Fixed possible infinite recursion on the Pushbullet integration in case of errors where the
+  error and close handlers keep calling each other in a loop.
+
+## [0.22.9] - 2022-01-06
+
+### Added
+
+- Added `rss` integration (replaces the cumbersome and deprecated `backend.http.poll`).
+
+### Fixed
+
+- Fixed timezone handling in calendar integrations.
+- Fixed handling of ignored directories in the `file.monitor` backend.
+
+## [0.22.8] - 2021-12-13
+
+### Added
+
+- Added support for audio tracks in Plex integration.
+
+### Changed
+
+- Web server uWSGI wrapper changed from `uwsgi` to `gunicorn`.
+
+### Fixed
+
+- Fixed client ID assignment logic in MQTT backends to prevent client ID clashes and reconnections
+  (closes #205).
+- Updated LTR559 integration to be compatible with the new API.
+- Updated Chromecast integration to be compatible with `pychromecast >= 10`.
+- Better handling of media errors.
+
+## [0.22.6] - 2021-11-27
+
+### Added
+
+- Added support for converting webpages to markdown in `http.webpage.simplify`
+  even if no `outfile` is specified.
+
+### Fixed
+
+- Improved robustness of the ICal calendar parser in case some fields (e.g. `*status`)
+  are not defined.
+
+## [0.22.5] - 2021-11-15
+
+### Added
+
+- Added `mastodon` plugin.
+- Added `chat.irc` plugin.
+- Added `mailgun` plugin.
+
+### Fixed
+
+- Fixed `switchbot.status` method in case of virtual devices.
+- Fixed `platypush[alexa]` optional package installation.
+
+## [0.22.4] - 2021-10-19
+
+### Added
+
+- Support for IR virtual devices in Switchbot plugin.
+- Added [`google.maps.get_travel_time`](https://docs.platypush.tech/platypush/plugins/google.maps.html#platypush.plugins.google.maps.GoogleMapsPlugin.get_travel_time)
+  method (closes #115).
+- Support for custom YouTube video/audio formats on media plugins.
+
+### Fixed
+
+- Responses for requests received over an MQTT backend are now delivered to the right topic
+  (`<device_base_topic>/responses/<msg_id>`).
+- Various fixes on media plugins.
+
+## [0.22.3] - 2021-10-01
+
+### Added
+
+- `gotify` integration (see #198).
+
+## [0.22.2] - 2021-09-25
+
+### Added
+
+- `ngrok` integration (see #196).
+
+## [0.22.1] - 2021-09-22
+
+### Fixed
+
+- `zigbee.mqtt` backend now no longer requires the MQTT backend/plugin to be enabled.
+
+- Fixed bug on empty popcorn API responses.
+
+### Changed
+
+- Created CI Gitlab pipeline to replace the Platypush event-based pre-existing pipeline.
+
+### Removed
+
+- Removed docs references to removed/abstract integrations.
+
+## [0.22.0] - 2021-09-16
+
+### Changed
+
+- Platypush now uses manifest files to describe plugins and backends. Each extension is now
+  expected to provide a `manifest.yaml` file in its folder, reporting its package name, pip
+  dependencies, required system packages and optional extra installation commands.
+
+- Refactored `platyvenv`, `platydock`, documentation generation and plugin management engine.
+  They are now both faster and more robust, since they can rely on the manifest definition to
+  operate instead of pydoc strings conventions or `config.yaml` conventions.
+
+- `platyvenv start`  now starts the environment process synchronously and it prints
+  stdout/stderr instead of redirecting it to the logs dir (previous behaviour:
+  `platyvenv start` used to start the process asynchronously and the logs were stored
+  to `~/.local/share/platypush/venv/<env>/logs/<stdout|stderr>.log`).
+
+### Removed
+
+- Removed `Homeseer` integration - it was based on a Python integration that has now been
+  pulled out of PyPI and GitHub. A new integration may come in the future if there is enough
+  demand for it.
+
+## [0.21.4] - 2021-08-24
+
+### Fixed
+
+- Fixed JWT token generation, since python-jwt >= 2.0 always returns strings (not bytes) upon `jwt.encode`.
+
+## [0.21.3] - 2021-07-28
+
+### Added
+
+- Added `sun` plugin for sunrise/sunset events.
+
+- Added `slack` integration.
+
+## [0.21.2] - 2021-07-20
+
+### Added
+
+- Added `music.spotify` backend to emulate a Spotify Connect receiver through Platypush.
+
+- Added `music.spotify` plugin.
+
+- Added `music.spotify` UI integration.
+
+## [0.21.1] - 2021-06-22
+
+### Added
+
+- Added `switchbot` plugin to interact with Switchbot devices over the cloud API instead of
+  directly accessing the device's Bluetooth interface.
+
+- Added `marshmallow` dependency - it will be used from now own to dump and document schemas
+  and responses instead of the currently mixed approach with `Response` objects and plain
+  dictionaries and lists.
+
+- Support for custom MQTT timeout on all the `zwavejs2mqtt` calls.
+
+- Added generic joystick backend `backend.joystick.jstest` which uses `jstest` from the
+  standard `joystick` system package to read the state of joysticks not compatible with
+  `python-inputs`.
+
+- Added PWM PCA9685 plugin.
+
+- Added Linux native joystick plugin, ``backend.joystick.linux``, for the cases where
+  ``python-inputs`` doesn't work and ``jstest`` is too slow.
+
+### Changed
+
+- `switch.switchbot` plugin renamed to `switchbot.bluetooth` plugin, while the new plugin
+  that uses the Switchbot API is simply named `switchbot`.
+
+### Fixed
+
+- More robust reconnection logic on the Pushbullet backend in case of websocket errors.
+
+## [0.21.0] - 2021-05-06
+
+### Added
+
+- Support for custom PopcornTime API mirror/base URL.
+
+- Full support for TV series search.
+
+### Fixed
+
+- Fixed torrent search (now using a different PopcornTime API mirror).
+
+- Migrated SASS engine from `node-sass` (currently deprecated and broken on Node 16) to `sass`.
+
+- Fixed alignment of Z-Wave UI header on Chrome/Webkit.
+
+## [0.20.10] - 2021-04-28
+
+### Fixed
+
+- Fixed zwave/zwavejs2mqtt interoperability.
+
+## [0.20.9] - 2021-04-12
+
 ### Added
 
 - Added zwavejs2mqtt integration (see [#186](https://git.platypush.tech/platypush/platypush/-/issues/186).
@@ -23,7 +303,7 @@ Given the high speed of development in the first phase, changes are being report
 
 - Added `<Camera>` dashboard widget.
 
-- Added support for custom dashboard widgets with customized (see https://git.platypush.tech/platypush/platypush/-/wikis/Backends#creating-custom-widgets).
+- Added support for custom dashboard widgets with customized (see https://git.platypush.tech/platypush/platypush/wiki/Backends#creating-custom-widgets).
 
 - Added support for controls on `music.mpd` dashboard widget.
 
@@ -70,7 +350,7 @@ Given the high speed of development in the first phase, changes are being report
 
 - Added support for a static list of devices to actively scan to the `bluetooth.scanner` backend
   (see [#174](https://git.platypush.tech/platypush/platypush/-/issues/174)).
-  
+
 - Added `weather.openweathermap` plugin and backend, which replaces `weather.darksky`, since the
   Darksky API will be completely shut down by the end of 2021.
 
@@ -78,14 +358,14 @@ Given the high speed of development in the first phase, changes are being report
 
 - Cron expressions should adhere to the UNIX cronjob standard and use the machine local time,
   not UTC, as a reference (closes [#173](https://git.platypush.tech/platypush/platypush/-/issues/173)).
-  
+
 - Better management of Z-Wave values types from the UI.
 
 - Disable logging for `ZwaveValueEvent` events - they tend to be very verbose and
   can impact the performance on slower devices. They will still be published to the
   websocket clients though, so you can still debug Z-Wave values issues from the browser
   developer console (enable debug traces).
-  
+
 - Added suffix to the `zigbee.mqtt` backend default `client_id` to prevent clashes with
   the default `mqtt` backend `client_id`.
 

CONTRIBUTING.md

@@ -29,9 +29,11 @@ Guidelines:
 
 - If the feature requires an optional dependency then make sure to document it:
 
-  - In the class docstring (see other plugins and backends for examples)
+  - In the class docstring (see other plugins and backends for examples).
   - In [`setup.py`](https://git.platypush.tech/platypush/platypush/-/blob/master/setup.py#L72) as
-    an `extras_require` entry
-  - In [`requirements.txt`](https://git.platypush.tech/platypush/platypush/-/blob/master/requirements.txt) -
-    if the feature is optional then leave it commented and add a one-line comment to explain which
-    plugin or backend requires it.
+    an `extras_require` entry.
+  - In the plugin/backend class pydoc string.
+  - In the `manifest.yaml` - refer to the Wiki (how to write
+    [plugins](https://git.platypush.tech/platypush/platypush/wiki/Writing-your-own-plugins)
+    and [backends](https://git.platypush.tech/platypush/platypush/wiki/Writing-your-own-backends))
+    for examples on how to write an extension manifest file.

MANIFEST.in

@@ -1,2 +1,4 @@
 recursive-include platypush/backend/http/webapp/dist *
 include platypush/plugins/http/webpage/mercury-parser.js
+include platypush/config/*.yaml
+global-include manifest.yaml

README.md

@@ -6,39 +6,82 @@ Platypush
 [![pip version](https://img.shields.io/pypi/v/platypush.svg?style=flat)](https://pypi.python.org/pypi/platypush/)
 [![License](https://img.shields.io/github/license/BlackLight/platypush.svg)](https://git.platypush.tech/platypush/platypush/-/blob/master/LICENSE.txt)
 [![Last Commit](https://img.shields.io/github/last-commit/BlackLight/platypush.svg)](https://git.platypush.tech/platypush/platypush/-/commits/master/)
+[![Join chat on Matrix](https://img.shields.io/matrix/:platypush?server_fqdn=matrix.platypush.tech)](https://matrix.to/#/#platypush:matrix.platypush.tech)
 [![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://git.platypush.tech/platypush/platypush/-/blob/master/CONTRIBUTING.md)
 [![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/BlackLight/platypush.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/BlackLight/platypush/context:python)
 [![Language grade: JavaScript](https://img.shields.io/lgtm/grade/javascript/g/BlackLight/platypush.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/BlackLight/platypush/context:javascript)
 
+<!-- toc -->
+
+- [Architecture](#architecture)
+  * [Plugins](#plugins)
+  * [Actions](#actions)
+  * [Backends](#backends)
+  * [Events](#events)
+  * [Hooks](#hooks)
+  * [Procedures](#procedures)
+  * [Cronjobs](#cronjobs)
+  * [The web interface](#the-web-interface)
+- [Installation](#installation)
+  * [System installation](#system-installation)
+    + [Install through `pip`](#install-through-pip)
+    + [Install through a system package manager](#install-through-a-system-package-manager)
+    + [Install from sources](#install-from-sources)
+  * [Installing the dependencies for your extensions](#installing-the-dependencies-for-your-extensions)
+    + [Install via `extras` name](#install-via-extras-name)
+    + [Install via `manifest.yaml`](#install-via-manifestyaml)
+    + [Check the instructions reported in the documentation](#check-the-instructions-reported-in-the-documentation)
+  * [Virtual environment installation](#virtual-environment-installation)
+  * [Docker installation](#docker-installation)
+- [Mobile app](#mobile-app)
+- [Tests](#tests)
+- [Funding](#funding)
+
+<!-- tocstop -->
+
 - Recommended read: [**Getting started with Platypush**](https://blog.platypush.tech/article/Ultimate-self-hosted-automation-with-Platypush).
 
-- The [blog](https://blog.platypush.tech) is in general a good place to get more insights on what you can build with it and inspiration about possible usages.
+- The [blog](https://blog.platypush.tech) is in general a good place to get
+  more insights on what you can build with it and inspiration about possible
+  usages.
 
-- The [wiki](https://git.platypush.tech/platypush/platypush/-/wikis/home) also contains many resources on getting started.
+- The [wiki](https://git.platypush.tech/platypush/platypush/wiki) also
+  contains many resources on getting started.
 
-- Extensive documentation for all the available integrations and messages [is available](https://docs.platypush.tech/).
+- Extensive documentation for all the available integrations and messages [is
+  available](https://docs.platypush.tech/).
 
-- If you have issues/feature requests/enhancement ideas please [create an issue](https://git.platypush.tech/platypush/platypush/-/issues).
+- If you have issues/feature requests/enhancement ideas please [create an
+  issue](https://git.platypush.tech/platypush/platypush/-/issues).
 
-- A [Reddit channel](https://www.reddit.com/r/platypush) is also available for more general questions.
+- A [Reddit channel](https://www.reddit.com/r/platypush) is also available for
+  more general questions.
+
+- A [Matrix instance](https://matrix.to/#/#platypush:matrix.platypush.tech) is
+  also available if you are looking for more interactive support.
 
 ---
 
-Platypush is a general-purpose extensible platform for automation and integration across multiple services and devices.
+Platypush is a general-purpose extensible platform for automation and
+integration across multiple services and devices.
 
-It enables users to create their own self-hosted pieces of automation based on events (*if this happens then do that*)
-and it provides a comprehensive and customizable user interface that collects everything you need to visualize and
-control under one roof.
+It enables users to create their own self-hosted pieces of automation based on
+events (*if this happens then do that*)
+and it provides a comprehensive and customizable user interface that collects
+everything you need to visualize and control under one roof.
 
-It takes some concepts from [IFTTT](https://ifttt.com), [Tasker](https://tasker.joaoapps.com/),
-[Microsoft Flow](https://flow.microsoft.com), [PushBullet](https://pushbullet.com) and
-[Home Assistant](https://www.home-assistant.io/) to provide an environment where the user can easily connect things
-together.
+It takes some concepts from [IFTTT](https://ifttt.com),
+[Tasker](https://tasker.joaoapps.com/), [Microsoft
+Flow](https://flow.microsoft.com), [PushBullet](https://pushbullet.com) and
+[Home Assistant](https://www.home-assistant.io/) to provide an environment
+where the user can easily connect things together.
 
-Its ideal home is a single-board computer like a RaspberryPi that you can configure to orchestrate any home automation
-and cloud automation in your own living room or garage, but it can easily run on any device that can run a Python
-interpreter, and the bar for the hardware requirements is very low as well - I use it to run pieces of automation on
-devices as powerful as a RaspberryPi Zero or an old Nokia N900 with Linux.
+Its ideal home is a single-board computer like a RaspberryPi that you can
+configure to orchestrate any home automation and cloud automation in your own
+living room or garage, but it can easily run on any device that can run a
+Python interpreter, and the bar for the hardware requirements is very low as
+well - I use it to run pieces of automation on devices as powerful as a
+RaspberryPi Zero or an old Nokia N900 with Linux.
 
 You can use Platypush to do things like:
 
@@ -47,8 +90,10 @@ You can use Platypush to do things like:
 - [Create custom and privacy-secure voice assistants that run custom hooks on your phrases](https://blog.platypush.tech/article/Build-custom-voice-assistants)
 - Build integrations between [sensors](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html),
   [cameras](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html),
-  [microphones](https://docs.platypush.tech/en/latest/platypush/plugins/sound.html) and
-  [machine learning models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html) to create smart
+  [microphones](https://docs.platypush.tech/en/latest/platypush/plugins/sound.html)
+  and [machine learning
+  models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html)
+  to create smart
   pieces of automation for e.g.
   [people detection](https://blog.platypush.tech/article/Detect-people-with-a-RaspberryPi-a-thermal-camera-Platypush-and-a-pinch-of-machine-learning)
   or [sound detection](https://blog.platypush.tech/article/Create-your-smart-baby-monitor-with-Platypush-and-Tensorflow)
@@ -60,35 +105,53 @@ You can use Platypush to do things like:
 - [Control your smart switches](https://docs.platypush.tech/en/latest/platypush/plugins/switch.html)
 - [Implement automated custom text-to-speech routines](https://docs.platypush.tech/en/latest/platypush/plugins/tts.html)
 - [Build any kind of interactions and automation routines with your Android device using Tasker](https://blog.platypush.tech/article/How-to-build-your-personal-infrastructure-for-data-collection-and-visualization)
-- Play [local videos](https://docs.platypush.tech/en/latest/platypush/plugins/media.mpv.html), YouTube videos and torrent media from any device and service, to any device
+- Play [local
+  videos](https://docs.platypush.tech/en/latest/platypush/plugins/media.mpv.html),
+  YouTube videos and torrent media from any device and service, to any device
 - [Get weather forecast events for your location and build automation routines on them](https://docs.platypush.tech/en/latest/platypush/plugins/weather.darksky.html)
 - [Create a custom single hub for Zigbee and Z-Wave smart devices](https://blog.platypush.tech/article/Transform-a-RaspberryPi-into-a-universal-Zigbee-and-Z-Wave-bridge)
-- Build your own web dashboard with calendar, weather, news and music controls (basically, anything that has a Platypush web widget)
+- Build your own web dashboard with calendar, weather, news and music controls
+  (basically, anything that has a Platypush web widget)
 - ...and much more (basically, anything that comes with a [Platypush plugin](https://docs.platypush.tech/en/latest/plugins.html))
 
 ## Architecture
 
-The architecture of Platypush consists of a few simple pieces, orchestrated by a configuration file stored by default
-under [`~/.config/platypush/config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml):
+The architecture of Platypush consists of a few simple pieces, orchestrated by
+a configuration file stored by default under
+[`~/.config/platypush/config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml):
 
-### [Plugins](https://docs.platypush.tech/en/latest/plugins.html)
+### Plugins
 
-They are integrations that do things - like
-[modify files](https://docs.platypush.tech/en/latest/platypush/plugins/file.html),
-[train and evaluate machine learning models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html),
-[control cameras](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html),
-[read sensors](https://docs.platypush.tech/en/latest/platypush/plugins/gpio.sensor.dht.html),
-[parse a web page](https://docs.platypush.tech/en/latest/platypush/plugins/http.webpage.html),
-[control lights](https://docs.platypush.tech/en/latest/platypush/plugins/light.hue.html),
-[send emails](https://docs.platypush.tech/en/latest/platypush/plugins/mail.smtp.html),
-[control Chromecasts](https://docs.platypush.tech/en/latest/platypush/plugins/media.chromecast.html),
-[run voice queries](https://docs.platypush.tech/en/latest/platypush/plugins/assistant.google.html),
-[handle torrent transfers](https://docs.platypush.tech/en/latest/platypush/plugins/torrent.html) or
-control [Zigbee](https://docs.platypush.tech/en/latest/platypush/plugins/zigbee.mqtt.html) or
-[Z-Wave](https://docs.platypush.tech/en/latest/platypush/plugins/zwave.html) devices.
+[Full list](https://docs.platypush.tech/en/latest/plugins.html)
 
-The configuration of a plugin matches one-on-one that of its documented class constructor, so it's very straightforward
-to write a configuration for a plugin by reading its documentation:
+Plugins are integrations that do things - like [modify
+files](https://docs.platypush.tech/en/latest/platypush/plugins/file.html),
+[train and evaluate machine learning
+models](https://docs.platypush.tech/en/latest/platypush/plugins/tensorflow.html),
+[control
+cameras](https://docs.platypush.tech/en/latest/platypush/plugins/camera.pi.html),
+[read
+sensors](https://docs.platypush.tech/en/latest/platypush/plugins/gpio.sensor.dht.html),
+[parse a web
+page](https://docs.platypush.tech/en/latest/platypush/plugins/http.webpage.html),
+[control
+lights](https://docs.platypush.tech/en/latest/platypush/plugins/light.hue.html),
+[send
+emails](https://docs.platypush.tech/en/latest/platypush/plugins/mail.smtp.html),
+[control
+Chromecasts](https://docs.platypush.tech/en/latest/platypush/plugins/media.chromecast.html),
+[run voice
+queries](https://docs.platypush.tech/en/latest/platypush/plugins/assistant.google.html),
+[handle torrent
+transfers](https://docs.platypush.tech/en/latest/platypush/plugins/torrent.html)
+or control
+[Zigbee](https://docs.platypush.tech/en/latest/platypush/plugins/zigbee.mqtt.html)
+or [Z-Wave](https://docs.platypush.tech/en/latest/platypush/plugins/zwave.html)
+devices.
+
+The configuration of a plugin matches one-on-one that of its documented class
+constructor, so it's very straightforward to write a configuration for a plugin
+by reading its documentation:
 
 ```yaml
 light.hue:
@@ -100,9 +163,11 @@ light.hue:
 
 ### Actions
 
-Plugins expose *actions*, that match one-on-one the plugin class methods denoted by `@action`, so it's very
-straightforward to invoke plugin actions by just reading the plugin documentation. They can be invoked directly from
-your own scripts or they can be sent to the platform through any supported channel as simple JSON messages:
+Plugins expose *actions*, that match one-on-one the plugin class methods
+denoted by `@action`, so it's very straightforward to invoke plugin actions by
+just reading the plugin documentation. They can be invoked directly from your
+own scripts or they can be sent to the platform through any supported channel
+as simple JSON messages:
 
 ```json
 {
@@ -114,37 +179,54 @@ your own scripts or they can be sent to the platform through any supported chann
 }
 ```
 
-### [Backends](https://docs.platypush.tech/en/latest/backends.html)
+### Backends
 
-They are background services that either listen for messages on channels (like an
-[HTTP backend](https://docs.platypush.tech/en/latest/platypush/backend/http.html), an
-[MQTT instance](https://docs.platypush.tech/en/latest/platypush/backend/mqtt.html), a
-[Kafka instance](https://docs.platypush.tech/en/latest/platypush/backend/kafka.html), a
-[Websocket service](https://docs.platypush.tech/en/latest/platypush/backend/websocket.html),
-[Pushbullet](https://docs.platypush.tech/en/latest/platypush/backend/pushbullet.html) etc.) or monitor a device or a
-service for events (like a [sensor](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html), a custom
-[voice assistant](https://docs.platypush.tech/en/latest/platypush/backend/assistant.google.html), a bridge running on a
-[Zigbee](https://docs.platypush.tech/en/latest/platypush/backend/zigbee.mqtt.html) or
-[Z-Wave](https://docs.platypush.tech/en/latest/platypush/backend/zwave.html), an
-[NFC card reader](https://docs.platypush.tech/en/latest/platypush/backend/nfc.html), a
-[MIDI device](https://docs.platypush.tech/en/latest/platypush/backend/midi.html), a
-[Telegram channel](https://docs.platypush.tech/en/latest/platypush/backend/chat.telegram.html), a
-[Bluetooth scanner](https://docs.platypush.tech/en/latest/platypush/backend/bluetooth.scanner.ble.html) etc.).
+[Full list](https://docs.platypush.tech/en/latest/backends.html)
 
-If a backend supports the execution of requests (e.g. HTTP, MQTT, Kafka, Websocket and TCP) then you can send requests
-to these services in JSON format. For example, in the case of the HTTP backend:
+They are background services that either listen for messages on channels (like
+an [HTTP
+backend](https://docs.platypush.tech/en/latest/platypush/backend/http.html), an
+[MQTT
+instance](https://docs.platypush.tech/en/latest/platypush/backend/mqtt.html), a
+[Kafka
+instance](https://docs.platypush.tech/en/latest/platypush/backend/kafka.html),
+a [Websocket
+service](https://docs.platypush.tech/en/latest/platypush/backend/websocket.html),
+[Pushbullet](https://docs.platypush.tech/en/latest/platypush/backend/pushbullet.html)
+etc.) or monitor a device or a service for events (like a
+[sensor](https://docs.platypush.tech/en/latest/platypush/backend/sensor.html),
+a custom [voice
+assistant](https://docs.platypush.tech/en/latest/platypush/backend/assistant.google.html),
+a bridge running on a
+[Zigbee](https://docs.platypush.tech/en/latest/platypush/backend/zigbee.mqtt.html)
+or
+[Z-Wave](https://docs.platypush.tech/en/latest/platypush/backend/zwave.html),
+an [NFC card
+reader](https://docs.platypush.tech/en/latest/platypush/backend/nfc.html), a
+[MIDI
+device](https://docs.platypush.tech/en/latest/platypush/backend/midi.html), a
+[Telegram
+channel](https://docs.platypush.tech/en/latest/platypush/backend/chat.telegram.html),
+a [Bluetooth
+scanner](https://docs.platypush.tech/en/latest/platypush/backend/bluetooth.scanner.ble.html)
+etc.).
+
+If a backend supports the execution of requests (e.g. HTTP, MQTT, Kafka,
+Websocket and TCP) then you can send requests to these services in JSON format.
+For example, in the case of the HTTP backend:
 
 ```shell
-# Get a token
+    # Get a token
 curl -XPOST -H 'Content-Type: application/json' -d '
   {
     "username": "$YOUR_USER",
     "password": "$YOUR_PASSWORD"
   }' http://host:8008/auth
 
-# Execute a request
+    # Execute a request
 
-curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" -d '
+curl -XPOST -H 'Content-Type: application/json' \
+    -H "Authorization: Bearer $YOUR_TOKEN" -d '
   {
     "type": "request",
     "action": "tts.say",
@@ -154,33 +236,38 @@ curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_
   }' http://host:8008/execute
 ```
 
-### [Events](https://docs.platypush.tech/en/latest/events.html)
+### Events
 
-When a certain event occurs (e.g. a JSON request is received, or a
-[Bluetooth device is connected](https://docs.platypush.tech/en/latest/platypush/events/bluetooth.html#platypush.message.event.bluetooth.BluetoothDeviceConnectedEvent),
-or a
-[Flic button is pressed](https://docs.platypush.tech/en/latest/platypush/events/button.flic.html#platypush.message.event.button.flic.FlicButtonEvent),
-or some
-[speech is detected on the voice assistant service](https://docs.platypush.tech/en/latest/platypush/events/assistant.html#platypush.message.event.assistant.SpeechRecognizedEvent),
-or an
-[RSS feed has new items](https://docs.platypush.tech/en/latest/platypush/events/http.rss.html#platypush.message.event.http.rss.NewFeedEvent),
-or a
-[new email is received](https://docs.platypush.tech/en/latest/platypush/events/mail.html#platypush.message.event.mail.MailReceivedEvent),
-or a
-[new track is played](https://docs.platypush.tech/en/latest/platypush/events/music.html#platypush.message.event.music.NewPlayingTrackEvent),
-or an
-[NFC tag is detected](https://docs.platypush.tech/en/latest/platypush/events/nfc.html#platypush.message.event.nfc.NFCTagDetectedEvent),
-or
-[new sensor data is available](https://docs.platypush.tech/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataChangeEvent),
-or
-[a value of a Zigbee device changes](https://docs.platypush.tech/en/latest/platypush/events/zigbee.mqtt.html#platypush.message.event.zigbee.mqtt.ZigbeeMqttDevicePropertySetEvent),
-etc.), the associated backend will trigger an [event](https://docs.platypush.tech/en/latest/events.html).
+[Full list](https://docs.platypush.tech/en/latest/events.html)
+
+When a certain event occurs (e.g. a JSON request is received, or a [Bluetooth
+device is
+connected](https://docs.platypush.tech/en/latest/platypush/events/bluetooth.html#platypush.message.event.bluetooth.BluetoothDeviceConnectedEvent),
+or a [Flic button is
+pressed](https://docs.platypush.tech/en/latest/platypush/events/button.flic.html#platypush.message.event.button.flic.FlicButtonEvent),
+or some [speech is detected on the voice assistant
+service](https://docs.platypush.tech/en/latest/platypush/events/assistant.html#platypush.message.event.assistant.SpeechRecognizedEvent),
+or an [RSS feed has new
+items](https://docs.platypush.tech/en/latest/platypush/events/http.rss.html#platypush.message.event.http.rss.NewFeedEvent),
+or a [new email is
+received](https://docs.platypush.tech/en/latest/platypush/events/mail.html#platypush.message.event.mail.MailReceivedEvent),
+or a [new track is
+played](https://docs.platypush.tech/en/latest/platypush/events/music.html#platypush.message.event.music.NewPlayingTrackEvent),
+or an [NFC tag is
+detected](https://docs.platypush.tech/en/latest/platypush/events/nfc.html#platypush.message.event.nfc.NFCTagDetectedEvent),
+or [new sensor data is
+available](https://docs.platypush.tech/en/latest/platypush/events/sensor.html#platypush.message.event.sensor.SensorDataChangeEvent),
+or [a value of a Zigbee device
+changes](https://docs.platypush.tech/en/latest/platypush/events/zigbee.mqtt.html#platypush.message.event.zigbee.mqtt.ZigbeeMqttDevicePropertySetEvent),
+etc.), the associated backend will trigger an
+[event](https://docs.platypush.tech/en/latest/events.html).
 
 ### Hooks
 
-Event hooks are custom pieces of logic that will be run when a certain event is triggered. Hooks are the glue that
-connects events to actions, exposing a paradigm similar to IFTTT (_if a certain event happens then run these actions_).
-They can declared as:
+Event hooks are custom pieces of logic that will be run when a certain event is
+triggered. Hooks are the glue that connects events to actions, exposing a
+paradigm similar to IFTTT (_if a certain event happens then run these
+actions_). They can declared as:
 
 - Sections of the [`config.yaml`](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/config.yaml).
   Example:
@@ -204,9 +291,10 @@ event.hook.SearchSongVoiceCommand:
           resource: ${output[0]['file']}
 ```
 
-- Stand-alone Python scripts stored under `~/.config/platypush/scripts` and will be dynamically imported at start time.
+- Stand-alone Python scripts stored under `~/.config/platypush/scripts` and
+  will be dynamically imported at start time.
   [Example](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/hook.py):
-  
+
 ```python
 from platypush.event.hook import hook
 from platypush.utils import run
@@ -225,13 +313,17 @@ def on_music_play_command(event, title=None, artist=None, **context):
 
 ### Procedures
 
-Procedures are pieces of custom logic that can be executed as atomic actions using `procedure.<name>` as an action name.
-They can be defined either in the `config.yaml` or as Python scripts stored under `~/.config/platypush/scripts` -
-provided that the procedure is also imported in `~/.config/platypush/scripts/__init__.py` so it can be discovered by
-the service.
+Procedures are pieces of custom logic that can be executed as atomic actions
+using `procedure.<name>` as an action name.
 
-YAML example for a procedure that can be executed when we arrive home and turns on the lights if the luminosity is lower
-that a certain thresholds, says a welcome home message using the TTS engine and starts playing the music:
+They can be defined either in the `config.yaml` or as Python scripts stored
+under `~/.config/platypush/scripts` - provided that the procedure is also
+imported in `~/.config/platypush/scripts/__init__.py` so it can be discovered
+by the service.
+
+YAML example for a procedure that can be executed when we arrive home and turns
+on the lights if the luminosity is lower that a certain thresholds, says a
+welcome home message using the TTS engine and starts playing the music:
 
 ```yaml
 procedure.at_home:
@@ -254,7 +346,7 @@ procedure.at_home:
 Python example:
 
 ```python
-# Content of ~/.config/platypush/scripts/home.py
+    # Content of ~/.config/platypush/scripts/home.py
 from platypush.procedure import procedure
 from platypush.utils import run
 
@@ -268,11 +360,12 @@ def at_home(**context):
   run('music.mpd.play')
 ```
 
-In either case, you can easily trigger the at-home procedure by sending an action request message to a backend - for
-example, over the HTTP backend:
+In either case, you can easily trigger the at-home procedure by sending an
+action request message to a backend - for example, over the HTTP backend:
 
 ```shell
-curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_TOKEN" -d '
+curl -XPOST -H 'Content-Type: application/json' \
+    -H "Authorization: Bearer $YOUR_TOKEN" -d '
   {
     "type": "request",
     "action": "procedure.at_home"
@@ -281,15 +374,18 @@ curl -XPOST -H 'Content-Type: application/json' -H "Authorization: Bearer $YOUR_
 
 ### Cronjobs
 
-Cronjobs are pieces of logic that will be run at regular intervals, expressed in crontab-compatible syntax.
-They can be defined either in the `config.yaml` or as Python scripts stored under `~/.config/platypush/scripts` as
-functions labelled by the `@cron` decorator.
+Cronjobs are pieces of logic that will be run at regular intervals, expressed
+in crontab-compatible syntax. They can be defined either in the `config.yaml`
+or as Python scripts stored under `~/.config/platypush/scripts` as functions
+labelled by the `@cron` decorator.
 
-Note that seconds are also supported (unlike the standard crontab definition), but, for back-compatibility with the
-standard crontab format, they are at the end of the cron expression, so the expression is actually in the format
+Note that seconds are also supported (unlike the standard crontab definition),
+but, for back-compatibility with the standard crontab format, they are at the
+end of the cron expression, so the expression is actually in the format
 `<minute> <hour> <day_of_month> <month> <day_of_week> <second>`.
 
-YAML example for a cronjob that is executed every 30 seconds and checks if a Bluetooth device is nearby:
+YAML example for a cronjob that is executed every 30 seconds and checks if a
+Bluetooth device is nearby:
 
 ```yaml
 cron.check_bt_device:
@@ -308,7 +404,7 @@ cron.check_bt_device:
 Python example:
 
 ```python
-# Content of ~/.config/platypush/scripts/bt_cron.py
+    # Content of ~/.config/platypush/scripts/bt_cron.py
 from platypush.cron import cron
 from platypush.utils import run
 
@@ -323,15 +419,18 @@ def check_bt_device(**context):
 
 ### The web interface
 
-If [`backend.http`](https://docs.platypush.tech/en/latest/platypush/backend/http.html) is enabled then a web interface
-will be provided by default on `http://host:8008/`. Besides using the `/execute` endpoint for running requests, the
-built-in web server also provides a full-featured interface that groups together the controls for most of the plugins -
-e.g. sensors, switches, music controls and search, media library and torrent management, lights, Zigbee/Z-Wave devices
-and so on. The UI is responsive and mobile-friendly.
+If
+[`backend.http`](https://docs.platypush.tech/en/latest/platypush/backend/http.html)
+is enabled then a web interface will be provided by default on
+`http://host:8008/`. Besides using the `/execute` endpoint for running
+requests, the built-in web server also provides a full-featured interface that
+groups together the controls for most of the plugins - e.g. sensors, switches,
+music controls and search, media library and torrent management, lights,
+Zigbee/Z-Wave devices and so on. The UI is responsive and mobile-friendly.
 
-The web service also provides means for the user to create
-[custom dashboards](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/dashboard.xml) that can
-be used to show information from multiple sources on a large screen.
+The web service also provides means for the user to create [custom
+dashboards](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/conf/dashboard.xml)
+that can be used to show information from multiple sources on a large screen.
 
 ## Installation
 
@@ -340,36 +439,69 @@ be used to show information from multiple sources on a large screen.
 Platypush uses Redis to deliver and store requests and temporary messages:
 
 ```yaml
-# Example for Debian-based distributions
+    # Example for Debian-based distributions
 [sudo] apt-get install redis-server
 
-# Enable and start the service
+    # Enable and start the service
 [sudo] systemctl enable redis
 [sudo] systemctl start redis
 ```
 
-To install the core platform:
-
-* The `pip` way:
+#### Install through `pip`
 
 ```shell
 [sudo] pip3 install platypush
 ```
 
-* The sources way:
+#### Install through a system package manager
+
+Note: currently only Arch Linux and derived distributions are supported.
+
+You can either install the
+[`platypush`](https://aur.archlinux.org/packages/platypush) package (for the
+latest stable version) or the
+[`platypush-git`](https://aur.archlinux.org/packages/platypush-git) package
+(for the latest git version) through your favourite AUR package manager. For
+example, using `yay`:
+
+```shell
+yay platypush
+# Or
+yay platypush-git
+```
+
+The Arch Linux packages on AUR are automatically updated upon new git commits
+or tags.
+
+#### Install from sources
 
 ```shell
 git clone https://git.platypush.tech/platypush/platypush.git
 cd platypush
+[sudo] pip install .
+    # Or
 [sudo] python3 setup.py install
 ```
 
-Then install the extensions that you wish to use. There are a few ways to check the dependencies required by an
-extension:
+### Installing the dependencies for your extensions
 
-#### Check their `extras` name in [`extras_require` under `setup.py`](https://git.platypush.tech/platypush/platypush/-/blob/master/setup.py#L72).
+After installing the base platform, you may want to check the dependencies and
+configuration required by the extensions that you wish to use. There are a few
+ways to check the dependencies required by an extension:
 
-If you follow this route then you can install the extra dependencies in one of the following ways:
+#### Install via `extras` name
+
+All the extensions that require extra dependencies are listed in the
+[`extras_require` section under
+`setup.py`](https://git.platypush.tech/platypush/platypush/-/blob/master/setup.py#L72).
+
+#### Install via `manifest.yaml`
+
+All the plugins and backends have a `manifest.yaml` file in their source folder.
+Any extra dependencies are listed there
+
+If you followed the `extras` or `manifest.yaml` way to discover the
+dependencies, then you can install them in two ways:
 
 1. `pip` installation:
 
@@ -383,25 +515,18 @@ If you follow this route then you can install the extra dependencies in one of t
 cd $DIR_TO_PLATYPUSH
 [sudo] pip3 install '.[extra1,extra2,extra3]'
 ```
-  
-#### Check the dependencies/installation instructions reported under the plugin/backend documentation.
 
-If you follow this route then simply run the commands listed in the plugin/backend documentation to get the dependencies
-installed.
+#### Check the instructions reported in the documentation
 
-#### Check/uncomment the associated lines in [`requirements.txt`](https://git.platypush.tech/platypush/platypush/-/blob/master/requirements.txt).
+If you follow this route then simply run the commands listed in the
+[plugin/backend documentation](https://docs.platypush.tech) to get the
+dependencies installed.
 
-If you follow this route then uncomment the lines in
-[`requirements.txt`](https://git.platypush.tech/platypush/platypush/-/blob/master/requirements.txt) associated to the
-plugins/backends that you want to use and run:
-
-```shell
-[sudo] pip3 install -r requirements.txt
-```
-
-After installing the dependencies, create a configuration file under `~/.config/platypush/config.yaml` (the application
-can load the configuration from another location through the `-c` option) containing the configuration of the backend
-and plugins that you want to use, and add any hooks and procedures for your use case.
+After installing the dependencies, create a configuration file under
+`~/.config/platypush/config.yaml` (the application can load the configuration
+from another location through the `-c` option) containing the configuration of
+the backend and plugins that you want to use, and add any hooks and procedures
+for your use case.
 
 You can then start the service by simply running:
 
@@ -410,85 +535,100 @@ platypush
 ```
 
 It's advised to run it as a systemd service though - simply copy the provided
-[`.service` file](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/systemd/platypush.service) to
-`~/.config/systemd/user`, check if the path of `platypush` matches the path where it's installed on your system, and
-start the service via `systemctl`:
+[`.service`
+file](https://git.platypush.tech/platypush/platypush/-/blob/master/examples/systemd/platypush.service)
+to `~/.config/systemd/user`, check if the path of `platypush` matches the path
+where it's installed on your system, and start the service via `systemctl`:
 
 ```shell
 systemctl --user start platypush
 ```
 
-### [Virtual environment installation](https://git.platypush.tech/platypush/platypush/-/wikis/Run-platypush-in-a-virtual-environment)
+### Virtual environment installation
 
-Platypush provides a script named `platyvenv` that can parse a `config.yaml` and automatically create a virtual
-environment (under `~/.local/share/platypush/venv/<device_id>`) with all the dependencies required by the configured
-integrations.
+Platypush provides a script named `platyvenv` that can parse a `config.yaml`
+and automatically create a virtual environment (under
+`~/.local/share/platypush/venv/<device_id>`) with all the dependencies required
+by the configured integrations.
 
 1. Create the environment from a configuration file:
 
-```shell
-platyvenv build -c /path/to/config.yaml
-```
+    ```shell
+    platyvenv build -c /path/to/config.yaml
+    ```
 
 2. Start the service from the virtual environment:
 
-```shell
-# device_id matches either the hostname or the device_id in config.yaml
-platyvenv start device_id
-```
+    ```shell
+        # device_id matches either the hostname or the device_id in config.yaml
+    platyvenv start device_id
+    ```
 
 3. Stop the instance:
 
-```shell
-platyvenv stop device_id
-```
+    ```shell
+    platyvenv stop device_id
+    ```
 
 4. Remove the instance:
 
-```shell
-platyvenv rm device_id
-```
+    ```shell
+    platyvenv rm device_id
+    ```
 
-### [Docker installation](https://git.platypush.tech/platypush/platypush/-/wikis/Run-platypush-in-a-container)
+[Wiki instructions](https://git.platypush.tech/platypush/platypush/wiki/Run-platypush-in-a-virtual-environment)
 
-You can also install Platypush in a container - the application provides a script named `platydock` that automatically
-creates a container instance from a `config.yaml`:
+### Docker installation
+
+You can also install Platypush in a container - the application provides a
+script named `platydock` that automatically creates a container instance from a
+`config.yaml`:
 
 1. Create the container from a configuration file:
 
-```shell
-platydock build -c /path/to/config.yaml
-```
+    ```shell
+    platydock build -c /path/to/config.yaml
+    ```
 
 2. Start the container:
 
-```shell
-# device_id matches either the hostname or the device_id in config.yaml
-platydock start device_id
-```
+    ```shell
+        # device_id matches either the hostname or the device_id in config.yaml
+    platydock start device_id
+    ```
 
 3. Stop the instance:
 
-```shell
-platydock stop device_id
-```
+    ```shell
+    platydock stop device_id
+    ```
 
 4. Remove the instance:
 
-```shell
-platydock rm device_id
-```
+    ```shell
+    platydock rm device_id
+    ```
+
+Note that both the virtual environment and Docker container option offer the
+possibility to include extra YAML configuration files in the main `config.yaml`
+through the `include` directive (as long as they are in the same folder as the
+main `config.yaml`), as well as external Python scripts in a `scripts`
+directory in the same folder as the `config.yaml`.
+
+[Wiki instructions](https://git.platypush.tech/platypush/platypush/wiki/Run-platypush-in-a-container)
 
 ## Mobile app
 
-An [official Android app](https://f-droid.org/en/packages/tech.platypush.platypush/) is provided on the F-Droid store.
-It allows to easily discover and manage multiple Platypush services on a network through the web interface, and it
-easily brings the power of Platypush to your fingertips.
+An [official Android
+app](https://f-droid.org/en/packages/tech.platypush.platypush/) is provided on
+the F-Droid store. It allows to easily discover and manage multiple Platypush
+services on a network through the web interface, and it easily brings the power
+of Platypush to your fingertips.
 
 ## Tests
 
-To run the tests simply run `pytest` either from the project root folder or the `tests/` folder.
-Or run the following command from the project root folder:
+To run the tests simply run `pytest` either from the project root folder or the
+`tests/` folder. Or run the following command from the project root folder:
 
 ```shell
 python -m tests
@@ -500,10 +640,11 @@ python -m tests
 
 If you use and love Platypush, please consider [buying me a coffee/beer](https://paypal.me/fabiomanganiello).
 
-I've been working on Platypush all by myself in my spare time for the past few years, and I've made sure that it remains
-open and free.
+I've been working on Platypush all by myself in my spare time for the past few
+years, and I've made sure that it remains open and free.
 
-If you like this product, please consider supporting - I'm definitely not planning to get rich with this project, but
-I'd love to have at least the costs for the server covered by users.
+If you like this product, please consider supporting - I'm definitely not
+planning to get rich with this project, but I'd love to have at least the costs
+for the server covered by users.
 
 Issues and requests opened by donors will also be given priority over others.

bin/platyvenv

@@ -6,12 +6,12 @@
 # and automatically managed the required dependencies, as well as start,     #
 # stop and remove them                                                       #
 #                                                                            #
-# @author: Fabio Manganiello <blacklight86@gmail.com>                        #
+# @author: Fabio Manganiello <fabio@platypush.tech>                          #
 # @licence: MIT                                                              #
 ##############################################################################
 
 
-workdir=$HOME/.local/share/platypush/venv
+workdir="$HOME/.local/share/platypush/venv"
 
 function build {
     cfgfile=
@@ -35,88 +35,74 @@ function build {
     fi
 
     echo "Parsing configuration file"
-    deps=()
+    pip_cmd=
+    pkg_cmd=
     includes=()
+    cmd_exec=()
 
     while read -r line; do
-        echo ${line} | egrep '``pip install .+?``' > /dev/null 2>&1
-        if (( $? != 0 )); then
-            continue
-        fi
-
-        dep=$(echo ${line} | sed -r -e 's/.*``pip install (.+?)``.*/\1/')
-        deps+=("$dep")
-    done <<< $(python <<EOF
+      if echo "$line" | grep -E "^pip:\s*"; then
+        pip_cmd="$(echo "$line" | sed -r -e 's/^pip:\s*(.*)'/\\1/)"
+      elif echo "$line" | grep -E "^packages:\s*"; then
+        pkg_cmd="$(echo "$line" | sed -r -e 's/^packages:\s*(.*)'/\\1/)"
+      elif echo "$line" | grep -E "^exec:\s*"; then
+        cmd_exec+=("$(echo "$line" | sed -r -e 's/^exec:\s*(.*)'/\\1/)")
+      elif echo "$line" | grep -E "^include:\s*"; then
+        includes+=("$(echo "$line" | sed -r -e 's/^include:\s*(.*)'/\\1/)")
+      elif echo "$line" | grep -E "^device_id:\s*"; then
+        device_id="$(echo "$line" | sed -r -e 's/^device_id:\s*(.*)'/\\1/)"
+      fi
+    done <<< "$(python <<EOF
 from platypush.config import Config
-from platypush.context import get_plugin, get_backend, register_backends
+from platypush.utils.manifest import get_install_commands_from_conf
 
-Config.init('`realpath ${cfgfile}`')
-register_backends()
-backend_config = Config.get_backends()
+deps = get_install_commands_from_conf('$(realpath "${cfgfile}")')
+print(f'device_id: {Config.get("device_id")}')
 
-for name in Config.get_backends().keys():
-    backend = get_backend(name)
-    print(backend.__doc__)
+if deps.get('pip'):
+    print(f'pip: {deps["pip"]}')
 
-for name in Config.get_plugins().keys():
-    try:
-        plugin = get_plugin(name)
-        print(plugin.__doc__)
-    except:
-        pass
-EOF
-)
+if deps.get('packages'):
+    print(f'packages: {deps["packages"]}')
 
-    while read -r include; do
-        includes+=(${include})
-    done <<< $(python <<EOF
-from platypush.config import Config
-from platypush.context import get_plugin, get_backend, register_backends
-
-Config.init('`realpath ${cfgfile}`')
+for cmd in deps.get('exec', []):
+    print(f'exec: {cmd}')
 
 for include in Config._included_files:
-    print(include)
+    print(f'include: {include}')
 EOF
-)
+)"
 
-    device_id=$(python <<EOF
-from platypush.config import Config
-
-Config.init('`realpath ${cfgfile}`')
-print(Config.get('device_id'))
-EOF
-)
-
-    envdir=${workdir}/${device_id}
-    etcdir=${envdir}/etc/platypush
+    envdir="${workdir}/${device_id}"
+    etcdir="${envdir}/etc/platypush"
 
     echo "Preparing virtual environment for device $device_id"
     mkdir -p "$envdir"
     mkdir -p "$etcdir"
-    srcdir=`dirname "$cfgfile"`
+    srcdir=$(dirname "$cfgfile")
 
-    for ((i=0; $i < ${#includes[@]}; i++)); do
-        incdir=`dirname "${includes[$i]}"`
-        incdir=`realpath --relative-to="$srcdir" "$incdir"`
+    for ((i=0; i < ${#includes[@]}; i++)); do
+        incdir=$(dirname "${includes[$i]}")
+        incdir=$(realpath --relative-to="$srcdir" "$incdir")
         destdir="$etcdir/$incdir"
         mkdir -p "$destdir"
         cp "${includes[$i]}" "$destdir"
     done
 
     cp "$cfgfile" "$etcdir/config.yaml"
-    cfgfile=${etcdir}/config.yaml
+    cfgfile="${etcdir}/config.yaml"
 
-    python3 -m venv ${envdir}
-    cd ${envdir}
-    source ${envdir}/bin/activate
+    python3 -m venv "${envdir}"
+    cd "${envdir}" || exit 1
+    source "${envdir}/bin/activate"
 
     echo "Installing required dependencies"
+    # shellcheck disable=SC2086
+    [ -n "${pkg_cmd}" ] && sudo ${pkg_cmd}
+    [ -n "${pip_cmd}" ] && ${pip_cmd}
 
-    for ((i=0; $i < ${#deps[@]}; i++)); do
-        echo ${deps[$i]}
-    done | sort -u | while read dep; do
-        pip install ${dep}
+    for ((i=0; i < ${#cmd_exec[@]}; i++)); do
+        ${cmd_exec[$i]}
     done
 
     pip install --upgrade git+https://git.platypush.tech/platypush/platypush.git
@@ -130,44 +116,41 @@ function start {
     fi
 
     env=$1
-    envdir=${workdir}/${env}
-    logsdir=${envdir}/var/log/platypush
-    rundir=${envdir}/var/run
-    pidfile=${rundir}/platypush.pid
-    cfgfile=${envdir}/etc/platypush/config.yaml
+    envdir="${workdir}/${env}"
+    rundir="${envdir}/var/run"
+    pidfile="${rundir}/platypush.pid"
+    cfgfile="${envdir}/etc/platypush/config.yaml"
 
     if [[ ! -d "$envdir" ]]; then
         echo "No such directory: $envdir" >&2
         exit 1
     fi
 
-    mkdir -p ${logsdir}
-    mkdir -p ${rundir}
+    mkdir -p "${rundir}"
 
     if [[ -f "$pidfile" ]]; then
-        pid=`cat "$pidfile"`
-        if ps -p ${pid} | grep platypush; then
-            echo "Another instance (PID $pid) is running, please stop that instance first"
+        if pgrep -F "${pidfile}"; then
+            echo "Another instance (PID $(cat "${pidfile}")) is running, please stop that instance first"
             exit 1
         fi
 
-        echo "A PID file was found but the process doesn't seem to be running, starting anyway"
+        echo "A PID file was found but the process does not seem to be running, starting anyway"
         rm -f "$pidfile"
     fi
 
-    python3 -m venv ${envdir}
-    cd ${envdir}
+    python3 -m venv "${envdir}"
+    cd "${envdir}" || exit 1
     source bin/activate
-    bin/platypush -c "$cfgfile" -P "$pidfile" > ${logsdir}/stdout.log 2> ${logsdir}/stderr.log &
-    start_time=`date +'%s'`
+    bin/platypush -c "$cfgfile" -P "$pidfile" &
+    start_time=$(date +'%s')
     timeout=30
 
     while :; do
         [[ -f "$pidfile" ]] && break
-        now=`date +'%s'`
-        let elapsed=$now-$start_time
-        if (( ${elapsed} >= ${timeout} )); then
-            echo "Platypush instance '$env' didn't start within $timeout seconds" >&2
+        now=$(date +'%s')
+        elapsed=$(( now-start_time ))
+        if (( elapsed >= timeout )); then
+            echo "Platypush instance '$env' did not start within $timeout seconds" >&2
             exit 1
         fi
 
@@ -175,9 +158,11 @@ function start {
         sleep 1
     done
 
-    pid=`cat "$pidfile"`
+    pid=$(cat "$pidfile")
     echo
-    echo "Platypush environment $env started with PID $pid, logs dir: $logsdir"
+    echo "Platypush environment $env started with PID $pid"
+    wait "${pid}"
+    echo "Platypush environment $env terminated"
 }
 
 function stop {
@@ -187,9 +172,9 @@ function stop {
     fi
 
     env=$1
-    envdir=${workdir}/${env}
-    rundir=${envdir}/var/run
-    pidfile=${rundir}/platypush.pid
+    envdir="${workdir}/${env}"
+    rundir="${envdir}/var/run"
+    pidfile="${rundir}/platypush.pid"
 
     if [[ ! -d "$envdir" ]]; then
         echo "No such directory: $envdir" >&2
@@ -197,12 +182,13 @@ function stop {
     fi
 
     if [[ ! -f "$pidfile" ]]; then
-        echo "No pidfile found for instance "${env}""
+        echo "No pidfile found for instance \"${env}\""
         exit 1
     fi
 
-    pid=`cat "$pidfile"`
-    pids="$pid `ps --no-headers -o pid= --ppid $pid`"
+    pid=$(cat "$pidfile")
+    pids="$pid $(ps --no-headers -o pid= --ppid "$pid")"
+    # shellcheck disable=SC2086
     kill -9 ${pids}
     rm -f "$pidfile"
     echo "Instance '$env' with PID $pid stopped"
@@ -214,9 +200,9 @@ function rme {
         exit 1
     fi
 
-    envdir=${workdir}/$1
-    rundir=${envdir}/var/run
-    pidfile=${rundir}/platypush.pid
+    envdir="${workdir}/$1"
+    rundir="${envdir}/var/run"
+    pidfile="${rundir}/platypush.pid"
 
     if [[ ! -d "$envdir" ]]; then
         echo "No such directory: $envdir" >&2
@@ -224,14 +210,18 @@ function rme {
     fi
 
     if [[ -f "$pidfile" ]]; then
-        if ps -p `cat "$pidfile"` | grep platypush; then
-            echo "Another instance (PID $pidfile) is running, please stop that instance first"
+        if pgrep -F "${pidfile}"; then
+            echo "Another instance (PID $(cat "$pidfile")) is running, please stop that instance first"
             exit 1
         fi
 
-        echo "A PID file was found but the process doesn't seem to be running, removing anyway"
+        echo "A PID file was found but the process does not seem to be running, removing anyway"
     fi
 
+    echo "WARNING: This operation will permanently remove the Platypush environment $1"
+    echo -n "Are you sure you want to continue? (y/N) "
+    IFS= read -r answer
+    echo "$answer" | grep -E '^[yY]' >/dev/null || exit 0
     rm -rf "$envdir"
     echo "$envdir removed"
 }
@@ -247,13 +237,13 @@ fi
 
 action=$1
 shift
-mkdir -p ${workdir}
+mkdir -p "${workdir}"
 
+# shellcheck disable=SC2048,SC2086
 case ${action} in
-    'build') build;;
+    'build') build $*;;
     'start') start $*;;
     'stop') stop $*;;
     'rm') rme $*;;
     *) usage;;
 esac
-

docs/source/_ext/sphinx_marshmallow.py

@@ -0,0 +1,87 @@
+import importlib
+import json
+import os
+import re
+import sys
+from random import randint
+from typing import Union, List
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from marshmallow import fields
+
+
+class SchemaDirective(Directive):
+    """
+    Support for response/message schemas in the docs. Format: ``.. schema:: rel_path.SchemaClass(arg1=value1, ...)``,
+    where ``rel_path`` is the path of the schema relative to ``platypush/schemas``.
+    """
+    has_content = True
+    _schema_regex = re.compile(r'^\s*(.+?)\s*(\((.+?)\))?\s*$')
+    _schemas_path = os.path.abspath(
+        os.path.join(
+            os.path.dirname(os.path.relpath(__file__)), '..', '..', '..', 'platypush', 'schemas'))
+
+    sys.path.insert(0, _schemas_path)
+
+    @classmethod
+    def _get_field_value(cls, field):
+        metadata = getattr(field, 'metadata', {})
+        if metadata.get('example'):
+            return metadata['example']
+        if metadata.get('description'):
+            return metadata['description']
+
+        if isinstance(field, fields.Number):
+            return randint(1, 99)
+        if isinstance(field, fields.Boolean):
+            return bool(randint(0, 1))
+        if isinstance(field, fields.URL):
+            return 'https://example.org'
+        if isinstance(field, fields.List):
+            return [cls._get_field_value(field.inner)]
+        if isinstance(field, fields.Dict):
+            return {
+                cls._get_field_value(field.key_field) if field.key_field else 'key':
+                    cls._get_field_value(field.value_field) if field.value_field else 'value'
+            }
+        if isinstance(field, fields.Nested):
+            ret = {
+                name: cls._get_field_value(f)
+                for name, f in field.nested().fields.items()
+            }
+
+            return [ret] if field.many else ret
+
+        return str(field.__class__.__name__).lower()
+
+    def _parse_schema(self) -> Union[dict, List[dict]]:
+        m = self._schema_regex.match('\n'.join(self.content))
+        schema_module_name = '.'.join(['platypush.schemas', *(m.group(1).split('.')[:-1])])
+        schema_module = importlib.import_module(schema_module_name)
+        schema_class = getattr(schema_module, m.group(1).split('.')[-1])
+        schema_args = eval(f'dict({m.group(3)})') if m.group(3) else {}
+        schema = schema_class(**schema_args)
+        output = {
+            name: self._get_field_value(field)
+            for name, field in schema.fields.items()
+            if not field.load_only
+        }
+
+        return [output] if schema.many else output
+
+    def run(self):
+        content = json.dumps(self._parse_schema(), sort_keys=True, indent=2)
+        block = nodes.literal_block(content, content)
+        block['language'] = 'json'
+        return [block]
+
+
+def setup(app):
+    app.add_directive('schema', SchemaDirective)
+
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

docs/source/backends.rst

@@ -8,10 +8,8 @@ Backends
 
     platypush/backend/adafruit.io.rst
     platypush/backend/alarm.rst
-    platypush/backend/assistant.rst
     platypush/backend/assistant.google.rst
     platypush/backend/assistant.snowboy.rst
-    platypush/backend/bluetooth.rst
     platypush/backend/bluetooth.fileserver.rst
     platypush/backend/bluetooth.pushserver.rst
     platypush/backend/bluetooth.scanner.rst
@@ -19,9 +17,7 @@ Backends
     platypush/backend/button.flic.rst
     platypush/backend/camera.pi.rst
     platypush/backend/chat.telegram.rst
-    platypush/backend/clipboard.rst
     platypush/backend/covid19.rst
-    platypush/backend/dbus.rst
     platypush/backend/file.monitor.rst
     platypush/backend/foursquare.rst
     platypush/backend/github.rst
@@ -32,6 +28,8 @@ Backends
     platypush/backend/http.poll.rst
     platypush/backend/inotify.rst
     platypush/backend/joystick.rst
+    platypush/backend/joystick.jstest.rst
+    platypush/backend/joystick.linux.rst
     platypush/backend/kafka.rst
     platypush/backend/light.hue.rst
     platypush/backend/linode.rst
@@ -42,6 +40,7 @@ Backends
     platypush/backend/music.mopidy.rst
     platypush/backend/music.mpd.rst
     platypush/backend/music.snapcast.rst
+    platypush/backend/music.spotify.rst
     platypush/backend/nextcloud.rst
     platypush/backend/nfc.rst
     platypush/backend/nodered.rst
@@ -49,7 +48,6 @@ Backends
     platypush/backend/pushbullet.rst
     platypush/backend/redis.rst
     platypush/backend/scard.rst
-    platypush/backend/sensor.rst
     platypush/backend/sensor.accelerometer.rst
     platypush/backend/sensor.arduino.rst
     platypush/backend/sensor.battery.rst
@@ -62,9 +60,8 @@ Backends
     platypush/backend/sensor.leap.rst
     platypush/backend/sensor.ltr559.rst
     platypush/backend/sensor.mcp3008.rst
-    platypush/backend/sensor.motion.pwm3901.rst
+    platypush/backend/sensor.motion.pmw3901.rst
     platypush/backend/sensor.serial.rst
-    platypush/backend/stt.rst
     platypush/backend/stt.deepspeech.rst
     platypush/backend/stt.picovoice.hotword.rst
     platypush/backend/stt.picovoice.speech.rst
@@ -72,7 +69,6 @@ Backends
     platypush/backend/todoist.rst
     platypush/backend/travisci.rst
     platypush/backend/trello.rst
-    platypush/backend/weather.rst
     platypush/backend/weather.buienradar.rst
     platypush/backend/weather.darksky.rst
     platypush/backend/weather.openweathermap.rst

docs/source/conf.py

@@ -18,6 +18,7 @@ import sys
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath("./_ext"))
 
 
 # -- Project information -----------------------------------------------------
@@ -50,6 +51,7 @@ extensions = [
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx_rtd_theme',
+    'sphinx_marshmallow',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -87,8 +89,11 @@ pygments_style = 'sphinx'
 #
 # html_theme = 'haiku'
 # html_theme = 'sphinx_rtd_theme'
-html_theme = 'sphinx_material'
+html_theme = 'sphinx_book_theme'
 
+html_title = 'Platypush Documentation'
+html_logo = '../../assets/logo-64.png'
+html_favicon = '../../platypush/backend/http/webapp/public/favicon.ico'
 html_domain_indices = True
 
 # Theme options are theme-specific and customize the look and feel of a theme
@@ -96,45 +101,12 @@ html_domain_indices = True
 # documentation.
 #
 html_theme_options = {
-    'nav_title': 'Platypush documentation',
-    'repo_url': 'https://git.platypush.tech/platypush/platypush',
-    'repo_name': 'Source code',
-    'repo_type': 'gitlab',
-    'color_primary': 'green',
-    'color_accent': 'light-green',
-    'logo_icon': '&#128366',
-    'nav_links': [
-        {
-            'href': 'https://platypush.tech/',
-            'title': 'Homepage',
-            'internal': False,
-        },
-        {
-            'href': 'https://blog.platypush.tech/',
-            'title': 'Blog',
-            'internal': False,
-        },
-        {
-            'href': 'https://git.platypush.tech/platypush/platypush',
-            'title': 'Repository',
-            'internal': False,
-        },
-        {
-            'href': 'https://git.platypush.tech/platypush/platypush/-/wikis/home',
-            'title': 'Wiki',
-            'internal': False,
-        },
-        {
-            'href': 'https://chrome.google.com/webstore/detail/platypush/aphldjclndofhflbbdnmpejbjgomkbie',
-            'title': 'Chrome Extension',
-            'internal': False,
-        },
-        {
-            'href': 'https://addons.mozilla.org/en-US/firefox/addon/platypush/',
-            'title': 'Firefox Extension',
-            'internal': False,
-        },
-    ],
+    'toc_title': 'Platypush documentation',
+    'repository_url': 'https://git.platypush.tech/platypush/platypush',
+    'use_repository_button': True,
+    'use_issues_button': True,
+    'use_fullscreen_button': True,
+    'home_page_in_toc': True,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -150,9 +122,9 @@ html_theme_options = {
 # default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
 # 'searchbox.html']``.
 #
-html_sidebars = {
-    '**': ['logo-text.html', 'globaltoc.html', 'localtoc.html', 'searchbox.html']
-}
+# html_sidebars = {
+#     '**': ['logo-text.html', 'globaltoc.html', 'localtoc.html', 'searchbox.html']
+# }
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -223,6 +195,10 @@ intersphinx_mapping = {'https://docs.python.org/': None}
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+autodoc_default_options = {
+    'inherited-members': True,
+}
+
 autodoc_mock_imports = ['googlesamples.assistant.grpc.audio_helpers',
                         'google.assistant.embedded',
                         'google.assistant.library',
@@ -240,7 +216,7 @@ autodoc_mock_imports = ['googlesamples.assistant.grpc.audio_helpers',
                         'gevent.wsgi',
                         'Adafruit_IO',
                         'pyperclip',
-                        'dbus',
+                        'pydbus',
                         'inputs',
                         'inotify',
                         'omxplayer',
@@ -266,7 +242,7 @@ autodoc_mock_imports = ['googlesamples.assistant.grpc.audio_helpers',
                         'envirophat',
                         'gps',
                         'picamera',
-                        'pwm3901',
+                        'pmw3901',
                         'PIL',
                         'croniter',
                         'pyaudio',
@@ -300,7 +276,6 @@ autodoc_mock_imports = ['googlesamples.assistant.grpc.audio_helpers',
                         'gi',
                         'gi.repository',
                         'twilio',
-                        'pytz',
                         'Adafruit_Python_DHT',
                         'RPi.GPIO',
                         'RPLCD',
@@ -308,15 +283,25 @@ autodoc_mock_imports = ['googlesamples.assistant.grpc.audio_helpers',
                         'pysmartthings',
                         'aiohttp',
                         'watchdog',
+                        'pyngrok',
+                        'irc',
+                        'irc.bot',
+                        'irc.strings',
+                        'irc.client',
+                        'irc.connection',
+                        'irc.events',
+                        'defusedxml',
                         ]
 
 sys.path.insert(0, os.path.abspath('../..'))
 
+
 def skip(app, what, name, obj, skip, options):
     if name == "__init__":
         return False
     return skip
 
+
 def setup(app):
     app.connect("autodoc-skip-member", skip)
 

docs/source/events.rst

@@ -13,10 +13,12 @@ Events
     platypush/events/bluetooth.rst
     platypush/events/button.flic.rst
     platypush/events/camera.rst
+    platypush/events/chat.slack.rst
     platypush/events/chat.telegram.rst
     platypush/events/clipboard.rst
     platypush/events/covid19.rst
     platypush/events/custom.rst
+    platypush/events/dbus.rst
     platypush/events/distance.rst
     platypush/events/file.rst
     platypush/events/foursquare.rst
@@ -25,11 +27,14 @@ Events
     platypush/events/google.rst
     platypush/events/google.fit.rst
     platypush/events/google.pubsub.rst
+    platypush/events/gotify.rst
+    platypush/events/gpio.rst
     platypush/events/gps.rst
     platypush/events/http.rst
     platypush/events/http.hook.rst
     platypush/events/http.rss.rst
     platypush/events/inotify.rst
+    platypush/events/irc.rst
     platypush/events/joystick.rst
     platypush/events/kafka.rst
     platypush/events/light.rst
@@ -43,9 +48,12 @@ Events
     platypush/events/music.snapcast.rst
     platypush/events/nextcloud.rst
     platypush/events/nfc.rst
+    platypush/events/ngrok.rst
+    platypush/events/ntfy.rst
     platypush/events/ping.rst
     platypush/events/pushbullet.rst
     platypush/events/qrcode.rst
+    platypush/events/rss.rst
     platypush/events/scard.rst
     platypush/events/sensor.rst
     platypush/events/sensor.ir.rst
@@ -54,6 +62,7 @@ Events
     platypush/events/serial.rst
     platypush/events/sound.rst
     platypush/events/stt.rst
+    platypush/events/sun.rst
     platypush/events/tensorflow.rst
     platypush/events/todoist.rst
     platypush/events/torrent.rst

docs/source/index.rst

@@ -3,14 +3,16 @@ Platypush
 
 Welcome to the Platypush reference of available plugins, backends and event types.
 
-For more information on Platypush please check out:
+For more information on Platypush check out:
 
-* The `Gitlab page`_ of the project
+* The `main page`_ of the project
+* The `Gitea page`_ of the project
 * The `online wiki`_ for quickstart and examples
 * The `Blog articles`_ for inspiration on use-cases possible projects
 
-.. _Gitlab page: https://git.platypush.tech/platypush/platypush
-.. _online wiki: https://git.platypush.tech/platypush/platypush/-/wikis/home
+.. _main page: https://platypush.tech
+.. _Gitea page: https://git.platypush.tech/platypush/platypush
+.. _online wiki: https://git.platypush.tech/platypush/platypush/wiki
 .. _Blog articles: https://blog.platypush.tech
 
 .. toctree::
@@ -28,4 +30,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/source/platypush/backend/adafruit.io.rst

@@ -1,4 +1,4 @@
-``platypush.backend.adafruit.io``
+``adafruit.io``
 =================================
 
 .. automodule:: platypush.backend.adafruit.io

docs/source/platypush/backend/alarm.rst

@@ -1,4 +1,4 @@
-``platypush.backend.alarm``
+``alarm``
 ===========================
 
 .. automodule:: platypush.backend.alarm

docs/source/platypush/backend/assistant.google.rst

@@ -1,4 +1,4 @@
-``platypush.backend.assistant.google``
+``assistant.google``
 ======================================
 
 .. automodule:: platypush.backend.assistant.google

docs/source/platypush/backend/assistant.rst

@@ -1,5 +0,0 @@
-``platypush.backend.assistant``
-===============================
-
-.. automodule:: platypush.backend.assistant
-    :members:

docs/source/platypush/backend/assistant.snowboy.rst

@@ -1,4 +1,4 @@
-``platypush.backend.assistant.snowboy``
+``assistant.snowboy``
 =======================================
 
 .. automodule:: platypush.backend.assistant.snowboy

docs/source/platypush/backend/bluetooth.fileserver.rst

@@ -1,4 +1,4 @@
-``platypush.backend.bluetooth.fileserver``
+``bluetooth.fileserver``
 ==========================================
 
 .. automodule:: platypush.backend.bluetooth.fileserver

docs/source/platypush/backend/bluetooth.pushserver.rst

@@ -1,4 +1,4 @@
-``platypush.backend.bluetooth.pushserver``
+``bluetooth.pushserver``
 ==========================================
 
 .. automodule:: platypush.backend.bluetooth.pushserver

docs/source/platypush/backend/bluetooth.rst

@@ -1,5 +0,0 @@
-``platypush.backend.bluetooth``
-===============================
-
-.. automodule:: platypush.backend.bluetooth
-    :members:

docs/source/platypush/backend/bluetooth.scanner.ble.rst

@@ -1,4 +1,4 @@
-``platypush.backend.bluetooth.scanner.ble``
+``bluetooth.scanner.ble``
 ===========================================
 
 .. automodule:: platypush.backend.bluetooth.scanner.ble

docs/source/platypush/backend/bluetooth.scanner.rst

@@ -1,4 +1,4 @@
-``platypush.backend.bluetooth.scanner``
+``bluetooth.scanner``
 =======================================
 
 .. automodule:: platypush.backend.bluetooth.scanner

docs/source/platypush/backend/button.flic.rst

@@ -1,4 +1,4 @@
-``platypush.backend.button.flic``
+``button.flic``
 =================================
 
 .. automodule:: platypush.backend.button.flic

docs/source/platypush/backend/camera.pi.rst

@@ -1,4 +1,4 @@
-``platypush.backend.camera.pi``
+``camera.pi``
 ===============================
 
 .. automodule:: platypush.backend.camera.pi

docs/source/platypush/backend/chat.telegram.rst

@@ -1,4 +1,4 @@
-``platypush.backend.chat.telegram``
+``chat.telegram``
 ===================================
 
 .. automodule:: platypush.backend.chat.telegram

docs/source/platypush/backend/clipboard.rst

@@ -1,5 +0,0 @@
-``platypush.backend.clipboard``
-===============================
-
-.. automodule:: platypush.backend.clipboard
-    :members:

docs/source/platypush/backend/covid19.rst

@@ -1,4 +1,4 @@
-``platypush.backend.covid19``
+``covid19``
 =============================
 
 .. automodule:: platypush.backend.covid19

docs/source/platypush/backend/dbus.rst

@@ -1,5 +0,0 @@
-``platypush.backend.dbus``
-==========================
-
-.. automodule:: platypush.backend.dbus
-    :members:

docs/source/platypush/backend/file.monitor.rst

@@ -1,4 +1,4 @@
-``platypush.backend.file.monitor``
+``file.monitor``
 ==================================
 
 .. automodule:: platypush.backend.file.monitor

docs/source/platypush/backend/foursquare.rst

@@ -1,4 +1,4 @@
-``platypush.backend.foursquare``
+``foursquare``
 ================================
 
 .. automodule:: platypush.backend.foursquare

docs/source/platypush/backend/github.rst

@@ -1,4 +1,4 @@
-``platypush.backend.github``
+``github``
 ============================
 
 .. automodule:: platypush.backend.github

docs/source/platypush/backend/google.fit.rst

@@ -1,4 +1,4 @@
-``platypush.backend.google.fit``
+``google.fit``
 ================================
 
 .. automodule:: platypush.backend.google.fit

docs/source/platypush/backend/google.pubsub.rst

@@ -1,4 +1,4 @@
-``platypush.backend.google.pubsub``
+``google.pubsub``
 ===================================
 
 .. automodule:: platypush.backend.google.pubsub

docs/source/platypush/backend/gps.rst

@@ -1,4 +1,4 @@
-``platypush.backend.gps``
+``gps``
 =========================
 
 .. automodule:: platypush.backend.gps

docs/source/platypush/backend/http.poll.rst

@@ -1,4 +1,4 @@
-``platypush.backend.http.poll``
+``http.poll``
 ===============================
 
 .. automodule:: platypush.backend.http.poll

docs/source/platypush/backend/http.rst

@@ -1,4 +1,4 @@
-``platypush.backend.http``
+``http``
 ==========================
 
 .. automodule:: platypush.backend.http

docs/source/platypush/backend/inotify.rst

@@ -1,4 +1,4 @@
-``platypush.backend.inotify``
+``inotify``
 =============================
 
 .. automodule:: platypush.backend.inotify

docs/source/platypush/backend/joystick.jstest.rst

@@ -0,0 +1,5 @@
+``joystick.jstest``
+=====================================
+
+.. automodule:: platypush.backend.joystick.jstest
+    :members:

docs/source/platypush/backend/joystick.linux.rst

@@ -0,0 +1,5 @@
+``joystick.linux``
+====================================
+
+.. automodule:: platypush.backend.joystick.linux
+    :members:

docs/source/platypush/backend/joystick.rst

@@ -1,4 +1,4 @@
-``platypush.backend.joystick``
+``joystick``
 ==============================
 
 .. automodule:: platypush.backend.joystick

docs/source/platypush/backend/kafka.rst

@@ -1,4 +1,4 @@
-``platypush.backend.kafka``
+``kafka``
 ===========================
 
 .. automodule:: platypush.backend.kafka

docs/source/platypush/backend/light.hue.rst

@@ -1,4 +1,4 @@
-``platypush.backend.light.hue``
+``light.hue``
 ===============================
 
 .. automodule:: platypush.backend.light.hue

docs/source/platypush/backend/linode.rst

@@ -1,4 +1,4 @@
-``platypush.backend.linode``
+``linode``
 ============================
 
 .. automodule:: platypush.backend.linode

docs/source/platypush/backend/log.http.rst

@@ -1,4 +1,4 @@
-``platypush.backend.log.http``
+``log.http``
 ==============================
 
 .. automodule:: platypush.backend.log.http

docs/source/platypush/backend/mail.rst

@@ -1,4 +1,4 @@
-``platypush.backend.mail``
+``mail``
 ==========================
 
 .. automodule:: platypush.backend.mail

docs/source/platypush/backend/midi.rst

@@ -1,4 +1,4 @@
-``platypush.backend.midi``
+``midi``
 ==========================
 
 .. automodule:: platypush.backend.midi

docs/source/platypush/backend/mqtt.rst

@@ -1,4 +1,4 @@
-``platypush.backend.mqtt``
+``mqtt``
 ==========================
 
 .. automodule:: platypush.backend.mqtt

docs/source/platypush/backend/music.mopidy.rst

@@ -1,4 +1,4 @@
-``platypush.backend.music.mopidy``
+``music.mopidy``
 ==================================
 
 .. automodule:: platypush.backend.music.mopidy

docs/source/platypush/backend/music.mpd.rst

@@ -1,4 +1,4 @@
-``platypush.backend.music.mpd``
+``music.mpd``
 ===============================
 
 .. automodule:: platypush.backend.music.mpd

docs/source/platypush/backend/music.snapcast.rst

@@ -1,4 +1,4 @@
-``platypush.backend.music.snapcast``
+``music.snapcast``
 ====================================
 
 .. automodule:: platypush.backend.music.snapcast

docs/source/platypush/backend/music.spotify.rst

@@ -0,0 +1,5 @@
+``music.spotify``
+===================================
+
+.. automodule:: platypush.backend.music.spotify
+    :members:

docs/source/platypush/backend/nextcloud.rst

@@ -1,4 +1,4 @@
-``platypush.backend.nextcloud``
+``nextcloud``
 ===============================
 
 .. automodule:: platypush.backend.nextcloud

docs/source/platypush/backend/nfc.rst

@@ -1,4 +1,4 @@
-``platypush.backend.nfc``
+``nfc``
 =========================
 
 .. automodule:: platypush.backend.nfc

docs/source/platypush/backend/nodered.rst

@@ -1,4 +1,4 @@
-``platypush.backend.nodered``
+``nodered``
 =============================
 
 .. automodule:: platypush.backend.nodered

docs/source/platypush/backend/ping.rst

@@ -1,4 +1,4 @@
-``platypush.backend.ping``
+``ping``
 ==========================
 
 .. automodule:: platypush.backend.ping

docs/source/platypush/backend/pushbullet.rst

@@ -1,4 +1,4 @@
-``platypush.backend.pushbullet``
+``pushbullet``
 ================================
 
 .. automodule:: platypush.backend.pushbullet

docs/source/platypush/backend/redis.rst

@@ -1,4 +1,4 @@
-``platypush.backend.redis``
+``redis``
 ===========================
 
 .. automodule:: platypush.backend.redis

docs/source/platypush/backend/scard.rst

@@ -1,4 +1,4 @@
-``platypush.backend.scard``
+``scard``
 ===========================
 
 .. automodule:: platypush.backend.scard

docs/source/platypush/backend/sensor.accelerometer.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.accelerometer``
+``sensor.accelerometer``
 ==========================================
 
 .. automodule:: platypush.backend.sensor.accelerometer

docs/source/platypush/backend/sensor.arduino.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.arduino``
+``sensor.arduino``
 ====================================
 
 .. automodule:: platypush.backend.sensor.arduino

docs/source/platypush/backend/sensor.battery.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.battery``
+``sensor.battery``
 ====================================
 
 .. automodule:: platypush.backend.sensor.battery

docs/source/platypush/backend/sensor.bme280.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.bme280``
+``sensor.bme280``
 ===================================
 
 .. automodule:: platypush.backend.sensor.bme280

docs/source/platypush/backend/sensor.dht.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.dht``
+``sensor.dht``
 ================================
 
 .. automodule:: platypush.backend.sensor.dht

docs/source/platypush/backend/sensor.distance.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.distance``
+``sensor.distance``
 =====================================
 
 .. automodule:: platypush.backend.sensor.distance

docs/source/platypush/backend/sensor.distance.vl53l1x.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.distance.vl53l1x``
+``sensor.distance.vl53l1x``
 =============================================
 
 .. automodule:: platypush.backend.sensor.distance.vl53l1x

docs/source/platypush/backend/sensor.envirophat.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.envirophat``
+``sensor.envirophat``
 =======================================
 
 .. automodule:: platypush.backend.sensor.envirophat

docs/source/platypush/backend/sensor.ir.zeroborg.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.ir.zeroborg``
+``sensor.ir.zeroborg``
 ========================================
 
 .. automodule:: platypush.backend.sensor.ir.zeroborg

docs/source/platypush/backend/sensor.leap.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.leap``
+``sensor.leap``
 =================================
 
 .. automodule:: platypush.backend.sensor.leap

docs/source/platypush/backend/sensor.ltr559.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.ltr559``
+``sensor.ltr559``
 ===================================
 
 .. automodule:: platypush.backend.sensor.ltr559

docs/source/platypush/backend/sensor.mcp3008.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.mcp3008``
+``sensor.mcp3008``
 ====================================
 
 .. automodule:: platypush.backend.sensor.mcp3008

docs/source/platypush/backend/sensor.motion.pmw3901.rst

@@ -0,0 +1,5 @@
+``sensor.motion.pmw3901``
+=========================
+
+.. automodule:: platypush.backend.sensor.motion.pmw3901
+    :members:

docs/source/platypush/backend/sensor.motion.pwm3901.rst

@@ -1,5 +0,0 @@
-``platypush.backend.sensor.motion.pwm3901``
-===========================================
-
-.. automodule:: platypush.backend.sensor.motion.pwm3901
-    :members:

docs/source/platypush/backend/sensor.rst

@@ -1,6 +0,0 @@
-``platypush.backend.sensor``
-============================
-
-.. automodule:: platypush.backend.sensor
-    :members:
-

docs/source/platypush/backend/sensor.serial.rst

@@ -1,4 +1,4 @@
-``platypush.backend.sensor.serial``
+``sensor.serial``
 ===================================
 
 .. automodule:: platypush.backend.sensor.serial

docs/source/platypush/backend/stt.deepspeech.rst

@@ -1,4 +1,4 @@
-``platypush.backend.stt.deepspeech``
+``stt.deepspeech``
 ====================================
 
 .. automodule:: platypush.backend.stt.deepspeech

docs/source/platypush/backend/stt.picovoice.hotword.rst

@@ -1,4 +1,4 @@
-``platypush.backend.stt.picovoice.hotword``
+``stt.picovoice.hotword``
 ===========================================
 
 .. automodule:: platypush.backend.stt.picovoice.hotword

docs/source/platypush/backend/stt.picovoice.speech.rst

@@ -1,4 +1,4 @@
-``platypush.backend.stt.picovoice.speech``
+``stt.picovoice.speech``
 ==========================================
 
 .. automodule:: platypush.backend.stt.picovoice.speech

docs/source/platypush/backend/stt.rst

@@ -1,5 +0,0 @@
-``platypush.backend.stt``
-=========================
-
-.. automodule:: platypush.backend.stt
-    :members:

docs/source/platypush/backend/tcp.rst

@@ -1,4 +1,4 @@
-``platypush.backend.tcp``
+``tcp``
 =========================
 
 .. automodule:: platypush.backend.tcp

docs/source/platypush/backend/todoist.rst

@@ -1,4 +1,4 @@
-``platypush.backend.todoist``
+``todoist``
 =============================
 
 .. automodule:: platypush.backend.todoist

docs/source/platypush/backend/travisci.rst

@@ -1,4 +1,4 @@
-``platypush.backend.travisci``
+``travisci``
 ==============================
 
 .. automodule:: platypush.backend.travisci

docs/source/platypush/backend/trello.rst

@@ -1,4 +1,4 @@
-``platypush.backend.trello``
+``trello``
 ============================
 
 .. automodule:: platypush.backend.trello

docs/source/platypush/backend/weather.buienradar.rst

@@ -1,4 +1,4 @@
-``platypush.backend.weather.buienradar``
+``weather.buienradar``
 ========================================
 
 .. automodule:: platypush.backend.weather.buienradar

docs/source/platypush/backend/weather.darksky.rst

@@ -1,4 +1,4 @@
-``platypush.backend.weather.darksky``
+``weather.darksky``
 =====================================
 
 .. automodule:: platypush.backend.weather.darksky

docs/source/platypush/backend/weather.openweathermap.rst

@@ -1,4 +1,4 @@
-``platypush.backend.weather.openweathermap``
+``weather.openweathermap``
 ============================================
 
 .. automodule:: platypush.backend.weather.openweathermap

docs/source/platypush/backend/weather.rst

@@ -1,5 +0,0 @@
-``platypush.backend.weather``
-=============================
-
-.. automodule:: platypush.backend.weather
-    :members:

docs/source/platypush/backend/websocket.rst

@@ -1,4 +1,4 @@
-``platypush.backend.websocket``
+``websocket``
 ===============================
 
 .. automodule:: platypush.backend.websocket

docs/source/platypush/backend/wiimote.rst

@@ -1,4 +1,4 @@
-``platypush.backend.wiimote``
+``wiimote``
 =============================
 
 .. automodule:: platypush.backend.wiimote

docs/source/platypush/backend/zigbee.mqtt.rst

@@ -1,4 +1,4 @@
-``platypush.backend.zigbee.mqtt``
+``zigbee.mqtt``
 =================================
 
 .. automodule:: platypush.backend.zigbee.mqtt

docs/source/platypush/backend/zwave.mqtt.rst

@@ -1,4 +1,4 @@
-``platypush.backend.zwave.mqtt``
+``zwave.mqtt``
 ================================
 
 .. automodule:: platypush.backend.zwave.mqtt

docs/source/platypush/backend/zwave.rst

@@ -1,4 +1,4 @@
-``platypush.backend.zwave``
+``zwave``
 ===========================
 
 .. automodule:: platypush.backend.zwave

docs/source/platypush/events/adafruit.rst

@@ -1,4 +1,4 @@
-``platypush.message.event.adafruit``
+``adafruit``
 ====================================
 
 .. automodule:: platypush.message.event.adafruit

docs/source/platypush/events/alarm.rst

@@ -1,4 +1,4 @@
-``platypush.message.event.alarm``
+``alarm``
 =================================
 
 .. automodule:: platypush.message.event.alarm

docs/source/platypush/events/application.rst

@@ -1,4 +1,4 @@
-``platypush.message.event.application``
+``application``
 =======================================
 
 .. automodule:: platypush.message.event.application