npm/jedi: new js package

This adds a new javascript package for distributing the pybricks-jedi
Python package and it's dependencies via the npm ecosystem for use in
Pybricks Code.

.github/workflows/build.yml

@@ -3,7 +3,19 @@
 
 name: Build Python package and docs
 
-on: [ push, pull_request ]
+on: 
+  push:
+    tags-ignore:
+      - "*"
+  pull_request:
+    paths:
+      - doc/**
+      - src/**
+      - poetry.lock
+      - poetry.toml
+      - pyproject.toml
+      - setup.cfg
+
 
 jobs:
   build:
@@ -35,9 +47,9 @@ jobs:
       run: poetry run doc8
     - name: Build html docs for Read the Docs
       run: poetry run make -C doc html
-    - name: Instal IDE docs dependencies
+    - name: Install IDE docs dependencies
       run: |
         sudo apt-get update
         sudo apt-get install dvisvgm preview-latex-style texlive texlive-fonts-extra texlive-latex-extra
     - name: Build html docs for Pybricks Code IDE
-      run: poetry run make -C doc html SOURCEDIR=ide
+      run: poetry run make -C doc html TAG=ide

.github/workflows/jedi.yml

@@ -0,0 +1,36 @@
+name: pybricks_jedi
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    if: github.ref_type != 'tag'
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: "3.10"
+    - run: pipx install poetry
+    - run: poetry install
+      working-directory: ./jedi
+    - run: poetry run pytest -vv
+      working-directory: ./jedi
+
+  publish:
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'pybricks_jedi/')
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: "3.10"
+    - run: pipx install poetry
+    - run: poetry install
+      working-directory: ./jedi
+    - run: poetry build
+      working-directory: ./jedi
+    - run: poetry publish
+      working-directory: ./jedi
+      env:
+        POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_PYBRICKS_JEDI_TOKEN }}

.github/workflows/publish-ide-docs.yml

@@ -31,8 +31,8 @@ jobs:
         node-version: '14.x'
         registry-url: 'https://registry.npmjs.org'
     - run: yarn build
-      working-directory: doc/ide
+      working-directory: npm/ide-docs
     - run: yarn publish
-      working-directory: doc/ide
+      working-directory: npm/ide-docs
       env:
         NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.github/workflows/publish-jedi.yml

@@ -0,0 +1,23 @@
+name: Release @pybricks/jedi
+
+on:
+  push:
+    tags: 
+    - '@pybricks/jedi/**'
+
+jobs:
+  publish_ide_docs:
+    runs-on: ubuntu-22.04
+    steps:
+    - uses: actions/checkout@v2
+    # Setup .npmrc file to publish to npm
+    - uses: actions/setup-node@v3
+      with:
+        node-version: '16.x'
+        registry-url: 'https://registry.npmjs.org'
+    - run: ./build.py
+      working-directory: npm/jedi
+    - run: yarn publish
+      working-directory: npm/jedi/build
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NODE_AUTH_TOKEN }}

.gitignore

@@ -26,8 +26,9 @@ build/
 build-*/
 _build/
 
-# Test failure outputs
+# Tests
 ######################
+.pytest_cache/
 tests/*.exp
 tests/*.out
 
@@ -57,3 +58,4 @@ genrst/
 # Virtual environment
 ######################
 .venv/
+.python-version

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+#
+# Settings in the readthedocs online dashboard will be ignored.
+
+# Required
+version: 2
+
+# Build documentation in the doc/main directory with Sphinx
+sphinx:
+   configuration: doc/main/conf.py
+
+# Build your docs in additional formats such as PDF
+formats:
+   - pdf
+
+# Set the version of Python and requirements required to build the docs
+python:
+   version: 3.8
+   install:
+   - requirements: rtd-requirements.txt

.vscode/settings.json

@@ -1,12 +1,26 @@
 {
-    "python.pythonPath": "${workspaceFolder}/.venv",
+    "files.exclude": {
+      "**/__pycache__": true,
+    },
+
+    "python.autoComplete.extraPaths": ["jedi/src"],
     "python.formatting.provider": "black",
-    "python.linting.pycodestyleEnabled": false,
+    "python.linting.pylintEnabled": false,
     "python.linting.flake8Enabled": true,
+    "python.linting.pycodestyleEnabled": false,
     "python.linting.enabled": true,
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "ms-python.python"
+    },
     "python.languageServer": "Pylance",
+    "python.testing.pytestArgs": [
+        "jedi/tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
     "files.associations": {"*.inc": "restructuredtext"},
-    "restructuredtext.confPath": "${workspaceFolder}/doc/api",
+    "restructuredtext.confPath": "${workspaceFolder}/doc/main",
     "spellright.language": [
         "en_US"
     ],
@@ -34,5 +48,12 @@
         "plaintext",
         "python",
         "restructuredtext",
-    ]
+    ],
+    "rewrap.wrappingColumn": 78,
+    "python.analysis.extraPaths": [
+        "jedi/src"
+    ],
+    "yaml.schemas": {
+        "https://json.schemastore.org/github-workflow.json": "file:///home/david/work/pybricks/pybricks-api/.github/workflows/build.yml"
+    },
 }

.vscode/spellright.dict

@@ -78,3 +78,4 @@ thermistor
 toctree
 TODO
 UART
+utf-8

CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
+
+## Unreleased
+
+### Added
+- Code auto-completion for `EssentialHub`.
+
+### Fixed
+- Fixed some type hints in `parameters` submodule.
+
+## 3.2.0b1-r3 - 2022-06-26
+
+### Fixed
+- Fixed more type hints and improved compatibility with jedi.
+
+## 3.2.0b1-r2 - 2022-06-24
+
+### Changed
+- Moved remaining type hints from `.pyi` files to the python stub modules, and
+  fixed numerous errors in the type hints throughout.
+
+## 3.2.0b1-r1 - 2022-06-09
+
+## Added
+- Added `__init__.py` to `pybricks` package.
+
+## 3.2.0b1 - 2022-06-02
+
+### Added
+- Code auto-completion for `hub.charger`, `hub.imu` and `hub.system`.
+- Moved typing from several `.pyi` files to the actual python modules.
+
+### Fixed
+- Fixed code completion for `DCMotor` and `Motor` classes in MS Python VS Code extension.
+- Fixed missing `DCMotor` type in `ev3devices`.
+- Fixed type hint for `Motor.reset_angle()` in `pupdevices`.
+
+### Changed
+- Setter for acceleration can now also be used to set acceleration and
+  deceleration to different values, using a two-valued tuple.
+
+## 3.1.0 - 2021-12-16
+
+### Added
+- Added maximum voltage setter for `DCMotor` and `Motor`.
+- Documented `DriveBase.curve()` method.
+
+### Changed
+- Removed `duty` setting from `Control.limits` method.
+- Removed `integral_range` setting from `Control.pid` method.
+
+### Fixed
+- Fixed link to Color Light Matrix page.
+- Fixed link to Inventor Hub page.
+
+## 3.1.0rc1 - 2021-11-19
+
+### Added
+- Added `ColorLightMatrix` class.
+- Added `LWP3Device` class.
+
+**NOTE: version number after this point were from JavaScript package and do
+not correspond to Pybricks firmware version numbers.**
+
+## 1.6.0 - 2021-08-30
+
+### Added
+- MicroPython module documentation.
+- Examples for hub system functions including stop button and shutdown.
+
+### Changed
+- Build IDE docs as main docs with minor changes, instead of a completely
+  separate build.
+- Moved motor control documentation to the motor page.
+
+## 1.5.0 - 2021-07-01
+
+### Added
+- Documentation for Powered Up Remote Control.
+
+## 1.4.0 - 2021-06-23
+
+### Added
+- Enabled beta content that was hidden for the 3.0 release.
+- Added notice about using the latest beta version.
+
+## 1.3.3 - 2021-05-21
+
+### Changed
+- Match example snippet styling to IDE.
+- Add more examples.
+
+## 1.3.2 - 2021-04-26
+
+## Changed
+- Theme style fixes.
+- Example code fixes
+- Match doc version to firmware version.
+
+## 1.3.1 - 2021-04-12
+
+### Changed
+- Upgrade sphinx and rtd-theme to fix style issues.
+
+## 1.3.0 - 2021-04-12
+
+### Removed
+- Removed features which not be in the official 3.0 release. These features
+  are still in beta. They'll come back in future releases once tested.
+
+## 1.2.0 - 2021-04-09
+
+### Changed
+- Moved installation guide to external site.
+
+## 1.1.1 - 2021-02-14
+
+### Added
+- Added installation guide.
+- Various documentation fixes.
+
+## 1.1.0 - 2021-01-28
+
+### Added
+- Scrollbar styling.
+
+## 1.0.0 - 2021-01-25
+
+### Added
+- Sphinx build output.

CONTRIBUTING.md

@@ -20,23 +20,103 @@ will actually be implemented.
 
 - Commit messages have a one-line subject, a blank line and a multiline body:
 
-        prefix: subject
+        prefix: Subject of the change.
 
         body...
 
-- Use a prefix to categorize the change. Usually this is the path the the file
-  being changed. 
-  - If it is a documentation change, it can be shortened to `doc/<file>` (omit
-    `api` from the path).
-  - If it is an API change (in the `pybricks` folder), write `api/<file>` 
-    instead of `pybricks/<file>`.
-- The subject briefly describes _what_ was changed, e.g. `fix typo`.
+- Use a prefix to categorize the change:
+  - Use the import path as the prefix whenever possible. Examples:
+     - pybricks.tools: Add StopWatch class.
+     - pybricks.tools: Reorganize RST files.
+     - pybricks.tools.StopWatch: Fix return type.
+     - pybricks.tools.wait: Add example of waiting.
+     - pybricks.pupdevices: Fix all sensor class ports.
+     - umath.sin: Fix spelling of Hypotenuse.
+  - If an import path makes no sense, just use the file path without
+    extensions:
+     - .vscode/settings: Fix file associations.
+- The subject briefly describes _what_ was changed. Use a short full sentence
+  as in the examples above.
 - The body describes _why_ the change was made, e.g. `The word "sensor" was
   spelled incorrectly`.
-- See the [commit history][commits] for more examples.
 
 [commits]: https://github.com/pybricks/pybricks-api/commits/master
 
+**General docstring principles:**
+
+The stubs libraries in this repository have two different purposes:
+1. Auto-generating documentation with Sphinx. For this purpose, the
+   documentation should be concise and clear.
+2. Provide autocomplete and intellisense in code editors. For this purpose,
+   the code needs to be 100% correct. This way, computers can parse your code
+   correctly and tell you when something is wrong.
+
+Since these objectives don't always align, we address these separately in the
+stubs library:
+
+1. The first line(s) of the docstring contain the function or method signature
+   as it should be displayed in the human-readable documentation.
+2. The real function signature can be as complex as it needs to be to make it
+   correct for intellisense. Overloads can be uses if needed.
+
+In the rare case where the docstring signature is the same as the typed
+version, we'll still include it for consistency.
+
+**Docstring details:**
+
+Make sure to look at existing function signatures and docstrings for
+inspiration when documenting new functionality. As an example, consider:
+
+```python
+def run_until_stalled(
+    self,
+    speed: Number,
+    then: Stop = Stop.COAST,
+    duty_limit: Optional[Number] = None,
+) -> int:
+    """
+    run_until_stalled(speed, then=Stop.COAST, duty_limit=None) -> int: deg
+
+    Runs the motor at a constant speed until it stalls.
+
+    Arguments:
+        speed (Number, deg/s): Speed of the motor.
+        then (Stop): What to do after coming to a standstill.
+        duty_limit (Number, %): Duty cycle limit during this
+            command. This is useful to avoid applying the full motor
+            torque to a geared or lever mechanism. If it is ``None``, the
+            duty limit won't be changed during this command.
+
+    Returns:
+        Angle at which the motor becomes stalled.
+    """
+```
+The real method signature at the top contains the full detail, including the
+type of each argument and return value.
+
+The docstring starts with the signature. Use more than one signature if needed
+to represent overloaded methods. The signatures are written in the way they
+should be displayed in the docs:
+- Argument types are omitted because they are also shown with the argument
+  description below.
+- Default values should be given (``then=Stop.COAST``).
+- The return type should be given (``-> int``). When applicable, include
+  the unit of the return value, so it becomes ``-> int: deg``
+
+Then follows a concise description of what this method, function, or class
+does.
+
+Then follows a list of arguments:
+- For each argument, include the expected type and unit if applicable, e.g.
+  ``(int)`` or ``(Number, deg/s)``.
+- Use ``Number`` when ``int`` and ``float`` are both allowed.
+- If the description is long, use the indentation shown above.
+- Make it readable. Instead
+  of ``Union[float, SupportsFloat, complex, SupportsComplex]``,
+  just say _float or complex_.
+
+Then follows a description of the return value. The type is omitted here since
+it is already include in the docstring signature.
 
 **Development environment:**
 
@@ -46,8 +126,8 @@ Prerequisites:
 - [Python 3][python]
 - [Poetry][poetry]
 
-Information on installing prerequisites can be found on the [pybricks-micropython
-wiki][wiki].
+Information on installing prerequisites can be found on the
+[pybricks-micropython contributor's guide][contributing].
 
 Initial setup:
 
@@ -59,15 +139,24 @@ Build docs:
 
     # Linux
     poetry run make -C doc html
-    xdg-open doc/api/build/html/index.html
+    xdg-open doc/main/build/html/index.html
 
     # macOS
     poetry run make -C doc html
-    open doc/api/build/html/index.html
+    open doc/main/build/html/index.html
 
     # Windows (PowerShell)
     poetry run doc\make.bat html
-    Invoke-Item doc\api\build\html\index.html
+    Invoke-Item doc\main\build\html\index.html
+
+Building IDE docs variant:
+
+    # Linux/macOS
+    poetry run make -C doc html TAG=ide
+
+    # Windows (PowerShell)
+    $env:TAG="ide"
+    poetry run doc\make.bat html
 
 Linting:
 
@@ -78,4 +167,4 @@ Linting:
 [git]: https://git-scm.com/
 [python]: https://www.python.org/
 [poetry]: https://python-poetry.org/
-[wiki]: https://github.com/pybricks-micropython/wiki
+[contributing]: https://github.com/pybricks/pybricks-micropython/blob/master/CONTRIBUTING.md

doc/Makefile

@@ -5,12 +5,13 @@
 SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Pybricks
-SOURCEDIR     = api
+SOURCEDIR     = main
 BUILDDIR      = "$(SOURCEDIR)"/build
+TAG           = main
 
 # Put it first so that "make" without argument is like "make help".
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(TAG) $(O)
 
 .PHONY: help Makefile
 
@@ -21,4 +22,4 @@ diagrams:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) -t $(TAG) $(O)

doc/api/conf.py

@@ -1,22 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# Pybricks documentation build configuration file
-#
-import os
-
-# General information about the project.
-project = 'pybricks'
-copyright = '2018-2021 The Pybricks Authors'
-author = ''
-
-_TITLE = 'Pybricks Modules and Examples'
-_DISCLAIMER = 'LEGO, the LEGO logo, MINDSTORMS and the MINDSTORMS EV3 logo are\
-               trademarks and/or copyrights of the LEGO Group of companies \
-               which does not sponsor, authorize or endorse this site.'
-
-html_favicon = '../common/images/favicon.ico'
-html_logo = '../common/images/pybricks-logo-rtd.png'
-latex_logo = '../common/images/pybricks-logo-large.png'
-
-exec(open(os.path.abspath("../common/conf.py")).read())

doc/api/diagram_source/pupmotors.ldr

@@ -1,13 +0,0 @@
-0 Name: pupmotors.ldr
-0 Author: Pybricks {laurens@pybricks.com}
-0 !LICENSE MIT
-0 ROTATION CENTER 0 0 0 1 "Custom" 
-0 ROTATION CONFIG 0 0
-1 15 430 -96 190 0 0 1 1 0 0 0 1 0 54675c01.dat
-1 15 430 -96 400 0 0 1 1 0 0 0 1 0 54675c01.dat
-1 322 430 -72 30 0 0 1 1 0 0 0 1 0 54696c01.dat
-1 71 430 -72 -180 0 0 1 1 0 0 0 1 0 54696c01.dat
-1 71 190 -144 -180 1 0 0 0 1 0 0 0 1 22169c01.dat
-1 71 -20 -216 -140 1 0 0 0 1 0 0 0 1 22172c01.dat
-1 15 120 -320 160 1 0 0 0 1 0 0 0 1 26913c01.dat
-0

doc/api/hubs/cityhub.rst

@@ -1,51 +0,0 @@
-City Hub
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. figure:: ../../api/images/cityhub.png
-    :height: 15 em
-
-.. autoclass:: pybricks.hubs.CityHub
-    :no-members:
-
-    .. rubric:: Using the hub status light
-
-    .. automethod:: pybricks.hubs::CityHub.light.on
-
-    .. automethod:: pybricks.hubs::CityHub.light.off
-
-    .. automethod:: pybricks.hubs::CityHub.light.blink
-
-    .. automethod:: pybricks.hubs::CityHub.light.animate
-
-    .. rubric:: Using the battery
-
-    .. automethod:: pybricks.hubs::CityHub.battery.voltage
-
-    .. automethod:: pybricks.hubs::CityHub.battery.current
-
-Status light examples
----------------------
-
-Turning the light on and off
-****************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_cityhub/light_off.py
-
-Changing brightness and using custom colors
-*******************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_cityhub/light_hsv.py
-
-Making the light blink
-**********************
-
-.. literalinclude::
-    ../../../examples/pup/hub_cityhub/light_blink.py
-
-Creating light animations
-*************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_cityhub/light_animate.py

doc/api/index.rst

@@ -1,82 +0,0 @@
-Pybricks API Documentation
-==================================================================
-
-This documentation has everything you need to install Pybricks and
-run your first scripts.
-
-
-**Step 1: Install Pybricks**
-
-Pybricks scripts are the same across all hubs. The only difference is in how
-you install Pybricks and how you run scripts. To get started, click one of
-the platforms below.
-
-.. list-table::
-
-   * - **MINDSTORMS EV3**
-     - **Powered Up (Technic/City/BOOST)**
-     - **SPIKE / MINDSTORMS Inventor**
-
-   * - .. image:: ../api/images/ev3brick.png
-         :target: https://pybricks.com/install/mindstorms-ev3/installation
-
-     - .. figure:: ../api/images/powereduphubs.png
-         :target: https://pybricks.com/install/technic-boost-city/
-
-     - .. figure:: ../api/images/primeinventorhub.png
-          :target: https://pybricks.com/install/spike-mindstorms/
-
-
-**Step 2: Start coding!**
-
-After you've followed the installation steps for your hub,
-check out the Pybricks modules in the left hand menu to see what
-you can do.
-
-**Step 3: Share what you made (or ask for help!)**
-
-Got questions or issues? Please share your
-findings on our `support page`_ so we can make Pybricks even better.
-*Thank you!*
-
-
-.. _support page: https://github.com/pybricks/support/issues/
-
-.. toctree::
-    :maxdepth: 1
-    :caption: Table of Contents
-    :hidden:
-
-.. toctree::
-    :maxdepth: 1
-    :caption: Pybricks
-    :hidden:
-
-    Home Page <https://pybricks.com>
-    Installation <https://pybricks.com/install/>
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Pybricks Modules
-   :hidden:
-
-   hubs/index
-   pupdevices/index
-   ev3devices
-   nxtdevices
-   iodevices/index
-   parameters/index
-   tools/index
-   robotics
-   media
-   messaging
-   geometry
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Engineering Extras
-   :hidden:
-
-   signaltypes
-   motors
-..    frames

doc/api/iodevices/index.rst

@@ -1,61 +0,0 @@
-:mod:`iodevices <pybricks.iodevices>` -- Generic I/O Devices
-============================================================
-
-.. automodule:: pybricks.iodevices
-    :no-members:
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   pupdevice
-   i2cdevice
-   uartdevice
-   analogsensor
-   lumpdevice
-   dcmotor
-   ev3devsensor
-
-.. pybricks-classlink:: PUPDevice
-
-.. figure:: ../../api/images/sensor_pup.png
-   :width: 70 %
-   :target: pupdevice.html
-
-   This class is only available on Powered Up hubs.
-
-.. pybricks-classlink:: I2CDevice
-
-.. figure:: ../../api/images/sensor_rj12_bluegreen.png
-   :width: 25 %
-   :target: i2cdevice.html
-
-.. pybricks-classlink:: UARTDevice
-
-.. figure:: ../../api/images/sensor_rj12_gray.png
-   :width: 25 %
-   :target: uartdevice.html
-
-.. pybricks-classlink:: AnalogSensor
-
-.. figure:: ../../api/images/sensor_rj12_brown.png
-   :width: 25 %
-   :target: analogsensor.html
-
-.. pybricks-classlink:: LUMPDevice
-
-.. figure:: ../../api/images/sensor_rj12_green.png
-   :width: 25 %
-   :target: lumpdevice.html
-
-.. pybricks-classlink:: DCMotor
-
-.. figure:: ../../api/images/rcxmotor.png
-   :width: 40 %
-   :target: dcmotor.html
-
-.. pybricks-classlink:: Ev3devSensor
-
-.. figure:: ../../api/images/sensor_ev3dev.png
-   :width: 70 %
-   :target: ev3devsensor.html

doc/api/motors.rst

@@ -1,139 +0,0 @@
-More about Motors
-===========================================
-
-.. Motor Tips & Tricks
-.. ^^^^^^^^^^^^^^^^^^^
-
-.. The difference between ``run_angle`` and ``run_target``
-.. -------------------------------------------------------
-
-.. *TODO*
-
-.. .. _absangles:
-
-.. Absolute angles
-.. ----------------------------
-
-.. .. todo::
-
-..     This section will be included in a future release.
-
-.. .. _stalled:
-
-.. Using stall detection
-.. ---------------------
-
-.. .. todo::
-
-..     This section will be included in a future release.
-
-.. When a motor cannot move any further despite using the maximally allowed
-.. torque we say that the motor is stalled. Something could be blocking the
-.. motor, or the load is just too heavy. For example, if you manually hold
-.. the motor shaft still while the motor is busy executing a command, the
-.. motor will stall.
-
-.. What can I do with stall detection?
-.. +++++++++++++++++++++++++++++++++++
-
-.. Stall detection is useful to detect that a motor can't move any further.
-.. This can be used to detect an endpoint of a mechanism. For example, you
-.. can detect whether a robotic hand is fully closed, because the gripper
-.. motor simply can't go further. This way, you don't need a touch or light
-.. sensor to detect this.
-
-.. *TODO: How, what, why. Explain run_until_stalled. Rack & pinion example.*
-
-.. When is a motor stalled?
-.. ++++++++++++++++++++++++
-
-.. TODO
-
-.. .. _gears:
-
-.. Using gears
-.. -----------------
-
-.. .. todo::
-
-..     This section will be included in a future release.
-
-.. Many LEGO robots use mechanisms with gears to change the speed and torque
-.. output of a motor. Let's consider the following dial mechanism.
-
-.. *TODO: INSERT PICTURE OF MOTOR WITH 12z gear AND 36z gear.*
-
-.. This gear train slows down the dial on the output axle by a factor of 3.
-.. Therefore, if you want to rotate the dial by 90 degrees, the motor has to
-.. rotate by 270 degrees. To turn at 200 degrees per second, the motor has to
-.. turn at 600 degrees per second, and so on.
-
-.. To avoid using this factor 3 everywhere in your program, you can use the
-.. `gears` setting of the ``Motor`` object, as shown in this example::
-
-..     # This example uses the EV3 brick, but the same
-..     # technique applies to other programmable hubs.
-..     ev3 = EV3Brick()
-
-..     # Initialize the motor. See picture above.
-..     dial = Motor(Port.C, Direction.COUNTERCLOCKWISE, gears=[12, 36])
-
-..     # Turn the dial by 90-degrees
-..     dial.run_angle(500, 90)
-
-..     # Print the dial angle
-..     print(dial.angle())
-
-..     # Turn the dial back to the original position
-..     dial.run_target(500, 0)
-
-.. When you use any of the other methods, the same scaling is applied. For
-.. example, you can print the angle of the dial as shown above. This will print
-.. 90 (approximately), even though the motor has turned 270 degrees.
-
-.. Notice that there is no magic going on. It is just a convenient scaling
-.. function. This helps you organize your code. For example, if you change
-.. your mechanism to use different gears, you only have to change the first
-.. line of this example.
-
-.. _control:
-
-The Control Class
-^^^^^^^^^^^^^^^^^
-
-The ``Motor`` class uses PID control to accurately track your commanded target
-angles. Similarly, the ``DriveBase`` class uses two of such controllers:
-one to control the heading and one to control the traveled distance.
-
-You can change the control settings through the following attributes, which are
-instances of the ``Control`` class given below.:
-
-    - ``Motor.control``
-    - ``DriveBase.heading_control``
-    - ``DriveBase.distance_control``
-
-You can only change the settings while the controller is stopped. For example,
-you can set the settings at the beginning of your program. Alternatively, first
-call ``stop()`` to make your ``Motor`` or ``DriveBase`` stop, and then change
-the settings.
-
-.. autoclass:: pybricks._common.Control
-    :no-members:
-
-    .. rubric:: Status
-
-    .. automethod:: pybricks._common.Control.done
-
-    .. automethod:: pybricks._common.Control.stalled
-
-    .. automethod:: pybricks._common.Control.load
-
-    .. rubric:: Settings
-
-    .. automethod:: pybricks._common.Control.limits
-
-    .. automethod:: pybricks._common.Control.pid
-
-    .. automethod:: pybricks._common.Control.target_tolerances
-
-    .. automethod:: pybricks._common.Control.stall_tolerances

doc/api/parameters/port.rst

@@ -1,38 +0,0 @@
-Port
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. class:: Port
-
-    Input and output ports:
-
-    .. autoattribute:: pybricks.parameters.Port.A
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.B
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.C
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.D
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.E
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.F
-        :annotation:
-
-    EV3 Sensor ports:
-
-    .. autoattribute:: pybricks.parameters.Port.S1
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.S2
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.S3
-        :annotation:
-
-    .. autoattribute:: pybricks.parameters.Port.S4
-        :annotation:

doc/api/pupdevices/remote.rst

@@ -1,30 +0,0 @@
-Remote Control
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. figure:: ../../api/images/pupremote.png
-   :width: 60 %
-
-.. autoclass:: pybricks.pupdevices.Remote
-  :no-members:
-
-  .. autoattribute:: pybricks.pupdevices::Remote.address
-       :annotation:
-
-  .. automethod:: pybricks.pupdevices::Remote.light.on
-
-  .. automethod:: pybricks.pupdevices::Remote.light.off
-
-  .. automethod:: pybricks.pupdevices::Remote.buttons.pressed
-
-.. note::
-
-    The ``light`` and ``address`` features are not yet supported.
-
-Examples
--------------------
-
-Check which buttons are pressed
-*******************************
-
-.. literalinclude::
-    ../../../examples/pup/remote/basics.py

doc/common/conf.py

@@ -27,22 +27,20 @@ from docutils import nodes
 from docutils.parsers.rst.directives import flag
 from docutils.parsers.rst import Directive
 from sphinx.application import Sphinx
-from sphinx.domains.python import PyClassmember, PythonDomain
+from sphinx.addnodes import pending_xref
+from sphinx.environment import BuildEnvironment
+from sphinx.util.nodes import make_refnode
 import toml
 
-TOP_DIR = os.path.abspath(os.path.join('..', '..'))
-sys.path.insert(0, TOP_DIR)
-sys.path.append(os.path.abspath('../common/extensions'))
-
-from pybricks.hubs import EV3Brick  # noqa E402
-from pybricks.media.ev3dev import Image  # noqa E402
-from pybricks._common import Speaker  # noqa E402
+TOP_DIR = os.path.abspath(os.path.join("..", ".."))
+sys.path.insert(0, os.path.join(TOP_DIR, "src"))
+sys.path.append(os.path.abspath("../common/extensions"))
 
 # ON_RTD is whether we are on readthedocs.org
 # this line of code grabbed from docs.readthedocs.org
-ON_RTD = os.environ.get('READTHEDOCS', None) == 'True'
+ON_RTD = os.environ.get("READTHEDOCS", None) == "True"
 
-_pyproject = toml.load(os.path.join(TOP_DIR, 'pyproject.toml'))
+_pyproject = toml.load(os.path.join(TOP_DIR, "pyproject.toml"))
 
 # -- General configuration ------------------------------------------------
 
@@ -54,25 +52,29 @@ _pyproject = toml.load(os.path.join(TOP_DIR, 'pyproject.toml'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.napoleon',
-    'sphinx.ext.todo',
-    'sphinx.ext.mathjax',
-    'color',
-    'classlink',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.mathjax",
+    # Custom Pybricks extensions
+    "color",
+    "classlink",
+    "requirements",
+    "requirements-static",
+    "versionchanged",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['../common/_templates']
+templates_path = ["../common/_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -81,17 +83,17 @@ master_doc = 'index'
 # The full version, including alpha/beta/rc tags.
 release = "v" + _pyproject["tool"]["poetry"]["version"]
 # The short X.Y version.
-version = re.match(r'(v\d+\.\d+)', release)[0]
+version = re.match(r"(v\d+\.\d+)", release)[0]
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'xcode'
+pygments_style = "xcode"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
@@ -99,10 +101,10 @@ todo_include_todos = True
 # Figure numbering
 numfig = True
 numfig_format = {
-    'figure': 'Figure %s',
-    'table': 'Table %s',
-    'code-block': 'Listing %s',
-    'section': 'Section %s'
+    "figure": "Figure %s",
+    "table": "Table %s",
+    "code-block": "Listing %s",
+    "section": "Section %s",
 }
 
 # Find cross-reference errors
@@ -110,45 +112,49 @@ nitpicky = True
 
 # https://stackoverflow.com/a/30624034/1976323
 nitpick_ignore = [
-    ('py:class', 'bool'),
-    ('py:class', 'bytearray'),
-    ('py:class', 'bytes'),
-    ('py:class', 'callable'),
-    ('py:class', 'dict'),
-    ('py:class', 'float'),
-    ('py:class', 'int'),
-    ('py:class', 'iter'),
-    ('py:class', 'list'),
-    ('py:class', 'object'),
-    ('py:class', 'str'),
-    ('py:class', 'tuple'),
-    ('py:exc', 'OSError'),
-    ('py:exc', 'RuntimeError'),
-    ('py:exc', 'TypeError'),
-    ('py:exc', 'ValueError'),
+    ("py:class", "bool"),
+    ("py:class", "bytearray"),
+    ("py:class", "bytes"),
+    ("py:class", "callable"),
+    ("py:class", "dict"),
+    ("py:class", "float"),
+    ("py:class", "int"),
+    ("py:class", "iter"),
+    ("py:class", "list"),
+    ("py:class", "object"),
+    ("py:class", "str"),
+    ("py:class", "tuple"),
+    ("py:exc", "OSError"),
+    ("py:exc", "RuntimeError"),
+    ("py:exc", "TypeError"),
+    ("py:exc", "ValueError"),
 ]
 
+# not sure why, but this is needed for typing.IO in uselect
+nitpick_ignore.append(("py:obj", "typing.IO"))
+
 # -- Autodoc options ------------------------------------------------------
 
-autodoc_member_order = 'bysource'
+autodoc_member_order = "bysource"
 autodoc_default_options = {
-    'members': True,
-    'undoc-members': True,
+    "members": True,
+    "undoc-members": True,
 }
-autoclass_content = 'both'  # This ensures init arguments are not ignored
+autoclass_content = "both"  # This ensures init arguments are not ignored
 add_module_names = False  # Hide module name
 
 # -- Options for HTML output ----------------------------------------------
 
 if ON_RTD:
-    html_theme = 'default'
+    html_theme = "default"
 else:
     import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
+
+    html_theme = "sphinx_rtd_theme"
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 html_context = {
-    'disclaimer': _DISCLAIMER,
+    "disclaimer": _DISCLAIMER,
 }
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -161,14 +167,14 @@ html_context = {
 # documentation.
 #
 html_theme_options = {
-   'style_external_links': True,
-   'logo_only': True,
+    "style_external_links": True,
+    "logo_only": True,
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['../common/_static']
+html_static_path = ["../common/_static"]
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
@@ -176,9 +182,9 @@ html_static_path = ['../common/_static']
 # This is required for the alabaster theme
 # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
 html_sidebars = {
-    '**': [
-        'relations.html',  # needs 'show_related': True theme option to display
-        'searchbox.html',
+    "**": [
+        "relations.html",  # needs 'show_related': True theme option to display
+        "searchbox.html",
     ]
 }
 
@@ -188,7 +194,7 @@ html_scaled_image_link = False
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Pybricksdoc'
+htmlhelp_basename = "Pybricksdoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -197,14 +203,12 @@ latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
-
     # The font size ('10pt', '11pt' or '12pt').
     #
     # 'pointsize': '10pt',
-
     # Additional stuff for the LaTeX preamble.
     #
-    'preamble': r'''
+    "preamble": r"""
     \usepackage{CJKutf8}
     \makeatletter
     \fancypagestyle{normal}{
@@ -224,34 +228,46 @@ latex_elements = {
         \renewcommand{\footrulewidth}{0.4pt}
     }
     \makeatother
-    ''' % {
-        'disclaimer': ' '.join((_DISCLAIMER, '©', copyright)),
+    """
+    % {
+        "disclaimer": " ".join((_DISCLAIMER, "©", copyright)),
     },
-
     # Latex figure (float) alignment
     #
     # 'figure_align': 'htbp',
-    'extraclassoptions': 'openany,oneside',
-
-    'releasename': 'Version',
+    "extraclassoptions": "openany,oneside",
+    "releasename": "Version",
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, ''.join([project, '-v', version, '.tex']), _TITLE,
-     author, 'manual'),
+    (master_doc, "".join([project, "-v", version, ".tex"]), _TITLE, author, "manual"),
+]
+
+# -- Content control -----------------------------------------------------
+
+
+exclude_patterns = [
+    "ev3devices.rst",
+    "hubs/ev3brick.rst",
+    "iodevices/analogsensor.rst",
+    "iodevices/dcmotor.rst",
+    "iodevices/ev3devsensor.rst",
+    "iodevices/i2cdevice.rst",
+    "iodevices/lumpdevice.rst",
+    "iodevices/uartdevice.rst",
+    "media.rst",
+    "messaging.rst",
+    "nxtdevices.rst",
+    "tools/datalog.rst",
 ]
 
-# -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'pybricks', 'Pybricks Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "pybricks", "Pybricks Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -260,74 +276,96 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'Pybricks', 'Pybricks Documentation',
-     author, 'Pybricks', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "Pybricks",
+        "Pybricks Documentation",
+        author,
+        "Pybricks",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]
 
 
 # -- .. availability:: directive
 
+
 class AvailabilityDirective(Directive):
     has_content = True
     option_spec = {
-        'movehub': flag,
-        'cityhub': flag,
-        'technichub': flag,
-        'ev3dev-stretch': flag,
+        "movehub": flag,
+        "cityhub": flag,
+        "technichub": flag,
+        "ev3dev-stretch": flag,
     }
 
     def run(self):
         if not self.options:
-            raise self.error('Must specify at least one platform.')
+            raise self.error("Must specify at least one platform.")
         # TODO: make links to platform pages
-        return [nodes.emphasis(text='Availability: '),
-                nodes.Text(', '.join(self.options))]
+        return [
+            nodes.emphasis(text="Availability: "),
+            nodes.Text(", ".join(self.options)),
+        ]
+
+
+def on_missing_reference(
+    app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: nodes.Element
+) -> nodes.Element:
+    # The Number type alias is on the Signals and Units page instead of on the
+    # pybricks.parameters page so normal resolution doesn't work
+    if node["reftype"] == "class" and node["reftarget"] == "Number":
+        return make_refnode(
+            app.builder, node["refdoc"], "signaltypes", "numbers", contnode
+        )
+
+    # References with special characters can't exist, so we have to supress
+    # warnings when Sphinx tries to cross reference units like deg/s. For
+    # consistency, we also treat units without special characters this way.
+    for unit in [
+        "deg",
+        "deg/s",
+        "deg/s²",
+        "mm",
+        "mm/s",
+        "mm/s²",
+        "%",
+        "mV",
+        "mA",
+        "ms",
+        "mNm",
+        "Hz",
+        "°C",
+        "J",
+        "Ω",
+        "N",
+    ]:
+
+        # If they match on raw source, we are dealing with argument types.
+        if unit == contnode.rawsource:
+            # Return as-is to suppress missing cross reference warning. We
+            # could make this more fancy by returning an xref node that links
+            # to the signals page.
+            return contnode
+
+        # Return types are denoted as "int: deg"
+        try:
+            # Try to unpack the node.
+            ret_type, ret_unit = str(contnode).split(": ")
+        except ValueError:
+            # Not a valid format, so skip.
+            continue
+
+        # If it's a match, we could format the node so it looks a bit nicer.
+        # For now just keep the colon notation as is.
+        if unit == ret_unit:
+            return nodes.Text(f"{ret_type}: {ret_unit}")
 
 
 def setup(app: Sphinx):
-    app.add_directive('availability', AvailabilityDirective)
+    app.add_directive("availability", AvailabilityDirective)
+    app.connect("missing-reference", on_missing_reference)
 
 
 # -- Python domain hacks ---------------------------------------------------
-
-real_get_signature_prefix = PyClassmember.get_signature_prefix
-
-
-def get_signature_prefix(self, sig):
-    # hacks for battery and light
-    if sig.count('.') >= 2:
-        return ''
-    return real_get_signature_prefix(self, sig)
-
-
-PyClassmember.get_signature_prefix = get_signature_prefix
-
-
-# HACK: For certain hub attributes, we list the class members of the attributes
-# class as if the attribute was a nested class so that readers don't have to
-# skip around the docs as much. To make this work, we replace the attribute
-# values with the type and override PythonDomain.find_obj so that references
-# still work.
-
-base_find_obj = PythonDomain.find_obj
-
-
-def find_obj(self, env, modname, classname, name, type, searchmode=0):
-    if modname == 'pybricks.hubs':
-        if classname == 'screen':
-            if name.startswith('Font.') or name == 'Font':
-                modname = 'pybricks.media.ev3dev'
-            elif name.startswith('Image.') or name == 'Image':
-                modname = 'pybricks.media.ev3dev'
-            else:
-                classname = 'EV3Brick.screen'
-        elif classname == 'speaker':
-            classname = 'EV3Brick.speaker'
-    return base_find_obj(self, env, modname, classname, name, type, searchmode)
-
-
-PythonDomain.find_obj = find_obj
-
-EV3Brick.screen = Image
-EV3Brick.speaker = Speaker

doc/common/extensions/classlink.py

@@ -5,27 +5,31 @@ from docutils.parsers.rst import Directive
 class PybricksClasslinkDirective(Directive):
 
     required_arguments = 1
+    optional_arguments = 1
 
     def run(self):
-        # Get link name from sphinx-directive
+        # Get link and name from sphinx-directive
         name = self.arguments[0]
+        link = name if len(self.arguments) == 1 else self.arguments[1]
 
         html = (
-            '<a href="{0}.html">'.format(name.lower()) +
-            '<dl class="py class">' +
-            '<dt>' +
-            '<em class="property">class </em>' +
-            '<code class="sig-name descname">' + name + '</code>' +
-            '</dt>' +
-            '<dd></dd>' +
-            '</dl>' +
-            '</a>'
+            '<a href="{0}.html">'.format(link.lower())
+            + '<dl class="py class">'
+            + "<dt>"
+            + '<em class="property">class </em>'
+            + '<code class="sig-name descname">'
+            + name
+            + "</code>"
+            + "</dt>"
+            + "<dd></dd>"
+            + "</dl>"
+            + "</a>"
         )
 
         # Return the node
-        node = nodes.raw('', html, format="html")
+        node = nodes.raw("", html, format="html")
         return [node]
 
 
 def setup(app):
-    app.add_directive_to_domain('py', 'pybricks-classlink', PybricksClasslinkDirective)
+    app.add_directive_to_domain("py", "pybricks-classlink", PybricksClasslinkDirective)

doc/common/extensions/color.py

@@ -16,28 +16,27 @@ class PybricksColorDirective(Directive):
         color = getattr(Color, name)
 
         # Convert HSV to RGB
-        r, g, b = hsv_to_rgb(color.h/360, color.s/100, color.v/100)
+        r, g, b = hsv_to_rgb(color.h / 360, color.s / 100, color.v / 100)
 
         # Convert RGB to HEX
-        rgbhex = '#{0:02x}{1:02x}{2:02x}'.format(
-            round(r*255),
-            round(g*255),
-            round(b*255)
+        rgbhex = "#{0:02x}{1:02x}{2:02x}".format(
+            round(r * 255), round(g * 255), round(b * 255)
         )
 
         # Render a small block of the given color
         css = "background-color: {0}; color: {0}; width: 50px;".format(rgbhex)
 
         if name == "WHITE":
-            css += "border-style: solid; border-width: 0.5px;" + \
-                   "border-color: #666666;"
+            css += (
+                "border-style: solid; border-width: 0.5px;" + "border-color: #666666;"
+            )
 
         html = '<div id="test" style="{0}">_</div>'.format(css)
 
         # Return the node
-        node = nodes.raw('', html, format="html")
+        node = nodes.raw("", html, format="html")
         return [node]
 
 
 def setup(app):
-    app.add_directive_to_domain('py', 'pybricks-color', PybricksColorDirective)
+    app.add_directive_to_domain("py", "pybricks-color", PybricksColorDirective)

doc/common/extensions/requirements-static.py

@@ -0,0 +1,103 @@
+from os import path, makedirs
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+from sphinx.util.osutil import copyfile
+
+# Base feature set.
+FEATURES_SMALL = set()
+
+# Medium feature set.
+FEATURES_MEDIUM = FEATURES_SMALL | {
+    "pybricks-geometry",
+    "pybricks-iodevices",
+    "stm32-extra",
+    "stm32-float",
+}
+
+# Large feature set.
+FEATURES_LARGE = FEATURES_MEDIUM | set()
+
+# Features per hub.
+HUB_FEATURES = {
+    "movehub": {"movehub"} | FEATURES_SMALL,
+    "cityhub": {"cityhub"} | FEATURES_MEDIUM,
+    "technichub": {"technichub"} | FEATURES_MEDIUM,
+    "primehub": {"primehub", "inventorhub"} | FEATURES_LARGE,
+    "inventorhub": {"primehub", "inventorhub"} | FEATURES_LARGE,
+    "essentialhub": {"essentialhub"} | FEATURES_LARGE,
+}
+
+
+class PybricksRequirementsStaticDirective(Directive):
+
+    required_arguments = 0
+    optional_arguments = 10
+
+    def run(self):
+
+        # Copy required resources to static
+        # CC BY-SA 4.0 via https://stackoverflow.com/a/63728208
+        env = self.state.document.settings.env
+
+        destdir = path.join(env.app.builder.outdir, "_images")
+        if not path.exists(destdir):
+            makedirs(destdir)
+
+        for hub in HUB_FEATURES:
+            for compat in ("true", "false"):
+                uri = "compat_{0}_{1}_label.png".format(hub, compat)
+                src_uri = path.join(env.app.builder.srcdir, "images", uri)
+                build_uri = path.join(env.app.builder.outdir, "_images", uri)
+                copyfile(src_uri, build_uri)
+
+        # Get requirements from sphinx-directive.
+        requirements = set(self.arguments)
+
+        # Cell with image of a hub.
+        hub_cell = """
+        <th><div class="align-default">
+        <img alt="" src="{0}_images/compat_{1}_{2}_label.png">
+        </div></th>
+        """
+
+        # Determine how far up the tree we are to set correct image path.
+        current_document = env.docname
+        depth = len(current_document.split("/")) - 1
+        depth_path = "../" * depth
+
+        # Table row with hub images.
+        compat_row = "".join(
+            [
+                hub_cell.format(
+                    depth_path, hub, "true" if requirements <= features else "false"
+                )
+                for hub, features in HUB_FEATURES.items()
+            ]
+        )
+
+        # Generate full table.
+        html = """
+        <div class="wy-table-responsive">
+            <table class="docutils align-default">
+                <tbody>
+                    <tr>
+                        {0}
+                    </tr>
+                </tbody>
+            </table>
+        </div>
+        """.format(
+            compat_row
+        )
+
+        # Return the node.
+        node = nodes.raw("", html, format="html")
+        return [node]
+
+
+def setup(app):
+    app.add_directive_to_domain(
+        "py", "pybricks-requirements-static", PybricksRequirementsStaticDirective
+    )

doc/common/extensions/requirements.css

@@ -0,0 +1,44 @@
+/*MIT License
+
+Copyright (c) 2017 Robert, https://github.com/ulrobix/sphinxcontrib-contentui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. */
+
+.toggle-header {
+    display: block;
+    float: right;
+    clear: both;
+    cursor: pointer;
+}
+.toggle-header p {display: inline;}
+.toggle-header strong {color: #2980b9 }
+
+.toggle-header:after {
+    content: "Compatibility ▼";
+}
+
+.toggle-header.open:after {
+    content: "▲";
+}
+
+.toggle-content {
+    display: none;
+    margin-bottom: 0px;
+}
+

doc/common/extensions/requirements.js

@@ -0,0 +1,33 @@
+/*MIT License
+
+Copyright (c) 2017 Robert, https://github.com/ulrobix/sphinxcontrib-contentui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. */
+
+$(function() {
+    /**
+     * Toggle logic
+     */
+    $('.toggle-content').hide()
+    $('.toggle-header').click(function () {
+        $(this).toggleClass("open");
+        $(this).next('.toggle-content').toggle('400');
+    })
+});
+

doc/common/extensions/requirements.py

@@ -0,0 +1,79 @@
+# MIT License
+
+# Copyright (c) 2017 Robert, https://github.com/ulrobix/sphinxcontrib-requirements
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+
+import os
+from docutils.parsers.rst import Directive, directives
+from docutils import nodes
+from docutils.statemachine import StringList
+from sphinx.util.osutil import copyfile
+from sphinx.util import logging
+
+
+CSS_FILE = "requirements.css"
+JS_FILE = "requirements.js"
+
+
+class PybricksRequirementsDirective(Directive):
+    has_content = True
+    option_spec = {"header": directives.unchanged}
+
+    required_arguments = 0
+    optional_arguments = 10
+
+    def run(self):
+        node = nodes.container()
+        node["classes"].append("toggle-content")
+
+        par = nodes.container()
+        par["classes"].append("toggle-header")
+
+        content = ".. pybricks-requirements-static:: " + " ".join(self.arguments)
+
+        self.state.nested_parse(StringList([content]), self.content_offset, node)
+
+        return [par, node]
+
+
+def add_assets(app):
+    app.add_css_file(CSS_FILE)
+    app.add_js_file(JS_FILE)
+
+
+def copy_assets(app, exception):
+    if app.builder.name not in ["html", "readthedocs"] or exception:
+        return
+    logger = logging.getLogger(__name__)
+    logger.info("Copying requirements stylesheet/javascript... ", nonl=True)
+    dest = os.path.join(app.builder.outdir, "_static", CSS_FILE)
+    source = os.path.join(os.path.abspath(os.path.dirname(__file__)), CSS_FILE)
+    copyfile(source, dest)
+    dest = os.path.join(app.builder.outdir, "_static", JS_FILE)
+    source = os.path.join(os.path.abspath(os.path.dirname(__file__)), JS_FILE)
+    copyfile(source, dest)
+    logger.info("done")
+
+
+def setup(app):
+    app.add_directive("pybricks-requirements", PybricksRequirementsDirective)
+    app.connect("builder-inited", add_assets)
+    app.connect("build-finished", copy_assets)

doc/common/extensions/versionchanged.py

@@ -0,0 +1,31 @@
+"""This directive hides the builtin directives
+    * versionchanged
+    * versionadded
+    * deprecated
+when building documentation with the 'ide' tag.
+"""
+from docutils import nodes
+from docutils.parsers.rst import Directive
+
+
+class PybricksVersionDirective(Directive):
+
+    has_content = True
+
+    def run(self):
+        html = ""
+        node = nodes.raw("", html, format="html")
+        return [node]
+
+
+def setup(app):
+    if "ide" in app.tags.tags:
+        app.add_directive_to_domain(
+            "py", "deprecated", PybricksVersionDirective, override=True
+        )
+        app.add_directive_to_domain(
+            "py", "versionadded", PybricksVersionDirective, override=True
+        )
+        app.add_directive_to_domain(
+            "py", "versionchanged", PybricksVersionDirective, override=True
+        )

doc/ide/CHANGELOG.md

@@ -1,55 +0,0 @@
-# 1.5.0 - 2021-07-01
-
-## Added:
-- Documentation for Powered Up Remote Control.
-
-# 1.4.0 - 2021-06-23
-
-## Added:
-- Enabled beta content that was hidden for the 3.0 release.
-- Added notice about using the latest beta version.
-
-# 1.3.3 - 2021-05-21
-
-## Changed:
-- Match example snippet styling to IDE.
-- Add more examples.
-
-# 1.3.2 - 2021-04-26
-
-## Changed:
-- Theme style fixes.
-- Example code fixes
-- Match doc version to firmware version.
-
-# 1.3.1 - 2021-04-12
-
-## Changed:
-- Upgrade sphinx and rtd-theme to fix style issues.
-
-# 1.3.0 - 2021-04-12
-
-## Removed:
-- Removed features which not be in the official 3.0 release. These features
-  are still in beta. They'll come back in future releases once tested.
-
-# 1.2.0 - 2021-04-09
-
-## Changed:
-- Moved installation guide to external site.
-
-# 1.1.1 - 2021-02-14
-
-## Added:
-- Added installation guide.
-- Various documentation fixes.
-
-# 1.1.0 - 2021-01-28
-
-## Added:
-- Scrollbar styling.
-
-# 1.0.0 - 2021-01-25
-
-## Added:
-- Sphinx build output.

doc/ide/conf.py

@@ -1,33 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# Pybricks documentation build configuration file
-#
-import os
-
-# General information about the project.
-project = 'pybricks'
-copyright = '2018-2021 The Pybricks Authors'
-author = ''
-
-_TITLE = 'Pybricks Modules and Examples'
-_DISCLAIMER = ''
-
-html_favicon = '../common/images/favicon.ico'
-html_logo = '../common/images/pybricks-logo-rtd.png'
-html_show_copyright = False
-html_show_sphinx = False
-html_css_files = ['css/ide.css']
-html_js_files = ['js/ide.js']
-
-imgmath_image_format = 'svg'
-imgmath_use_preview = True  # requires Sphinx v3
-imgmath_latex_preamble = r'''
-\usepackage{newtxsf}
-'''
-
-exec(open(os.path.abspath("../common/conf.py")).read())
-
-extensions.remove('sphinx.ext.mathjax')  # noqa F821
-extensions.append('sphinx.ext.imgmath')  # noqa F821
-html_theme_options['prev_next_buttons_location'] = None  # noqa F821

doc/ide/diagram_source/Makefile

@@ -1,25 +0,0 @@
-
-SRC_DIR = .
-OUT_DIR = ../images
-
-POSTFIX := _label
-SVG := $(wildcard $(SRC_DIR)/*.svg)
-DIAGRAMS := $(patsubst $(SRC_DIR)/%.svg,$(OUT_DIR)/%$(POSTFIX).png,$(SVG))
-DIR := ${CURDIR}
-
-all: $(DIAGRAMS)
-
-clean:
-	rm -f $(DIAGRAMS)
-
-$(OUT_DIR)/%$(POSTFIX).png: $(SRC_DIR)/%.svg
-	if inkscape --version | grep -q "Inkscape 0"; then \
-		inkscape --file=$(DIR)/$< --export-area-drawing --export-png=$(DIR)/$@; \
-	else \
-		inkscape \
-			--export-area-drawing \
-			--export-background=white \
-			--export-background-opacity=1.0 \
-			--export-file=$(DIR)/$@ \
-			$(DIR)/$<; \
-	fi

doc/ide/geometry.rst

@@ -1 +0,0 @@
-.. include:: ../api/geometry.rst

doc/ide/hubs/cityhub.rst

@@ -1 +0,0 @@
-.. include:: ../../api/hubs/cityhub.rst

doc/ide/hubs/index.rst

@@ -1,43 +0,0 @@
-:mod:`hubs <pybricks.hubs>` -- Programmable Hubs
-================================================
-
-.. module:: pybricks.hubs
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   movehub
-   cityhub
-   technichub
-   primehub
-
-.. pybricks-classlink:: MoveHub
-
-.. figure:: ../../api/images/movehub.png
-    :height: 10 em
-    :target: movehub.html
-
-.. pybricks-classlink:: CityHub
-
-.. figure:: ../../api/images/cityhub.png
-    :height: 10 em
-    :target: cityhub.html
-
-.. pybricks-classlink:: TechnicHub
-
-.. figure:: ../../api/images/technichub.png
-    :height: 10 em
-    :target: technichub.html
-
-.. pybricks-classlink:: PrimeHub
-
-.. figure:: ../../api/images/primehub.png
-    :height: 10 em
-    :target: primehub.html
-
-.. pybricks-classlink:: InventorHub
-
-.. figure:: ../../api/images/inventorhub.png
-    :height: 10 em
-    :target: primehub.html

doc/ide/hubs/movehub.rst

@@ -1 +0,0 @@
-.. include:: ../../api/hubs/movehub.rst

doc/ide/hubs/primehub.rst

@@ -1 +0,0 @@
-.. include:: ../../api/hubs/primehub.rst

doc/ide/hubs/technichub.rst

@@ -1 +0,0 @@
-.. include:: ../../api/hubs/technichub.rst

doc/ide/index.rst

@@ -1,55 +0,0 @@
-Pybricks Documentation
-==================================================================
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Pybricks Modules
-   :hidden:
-
-   hubs/index
-   pupdevices/index
-   iodevices/index
-   parameters/index
-   tools/index
-   robotics
-   geometry
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Engineering Extras
-   :hidden:
-
-   signaltypes
-   motors
-
-.. note::
-
-   **You are using a new beta version of Pybricks!**
-
-   This is great for trying the very latest features, but some things
-   might not work.
-
-   If in doubt, use the `latest stable release`_. Please report any
-   issues via our `support page`_. Thanks!
-
-To begin, install the Pybricks firmware on your hub. Check
-`pybricks.com/install`_ to learn how.
-
-Use the ☰ menu to navigate all available classes, methods, and tools. A few
-commonly used devices and classes are listed below for quick reference.
-
-.. rubric:: Programmable Hubs
-
-.. figure:: ../api/images/hubsoverview.png
-   :width: 100 %
-   :target: hubs/index.html
-
-.. rubric:: Powered Up Motors and Sensors
-
-.. figure:: ../api/images/pupdevicesoverview.png
-   :width: 100 %
-   :target: pupdevices/index.html
-
-.. _pybricks.com/install: https://pybricks.com/install/
-.. _latest stable release: https://www.code.pybricks.com/
-.. _support page: https://github.com/pybricks/support

doc/ide/iodevices/index.rst

@@ -1,17 +0,0 @@
-:mod:`iodevices <pybricks.iodevices>` -- Generic I/O Devices
-============================================================
-
-.. automodule:: pybricks.iodevices
-    :no-members:
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   pupdevice
-
-.. pybricks-classlink:: PUPDevice
-
-.. figure:: ../../api/images/sensor_pup.png
-   :width: 70 %
-   :target: pupdevice.html

doc/ide/iodevices/pupdevice.rst

@@ -1 +0,0 @@
-.. include:: ../../api/iodevices/pupdevice.rst

doc/ide/motors.rst

@@ -1 +0,0 @@
-.. include:: ../api/motors.rst

doc/ide/parameters/button.rst

@@ -1 +0,0 @@
-.. include:: ../../api/parameters/button.rst

doc/ide/parameters/color.rst

@@ -1 +0,0 @@
-.. include:: ../../api/parameters/color.rst

doc/ide/parameters/direction.rst

@@ -1 +0,0 @@
-.. include:: ../../api/parameters/direction.rst

doc/ide/parameters/index.rst

@@ -1 +0,0 @@
-.. include:: ../../api/parameters/index.rst

doc/ide/parameters/side.rst

@@ -1 +0,0 @@
-.. include:: ../../api/parameters/side.rst

doc/ide/parameters/stop.rst

@@ -1 +0,0 @@
-.. include:: ../../api/parameters/stop.rst

doc/ide/pupdevices/colordistancesensor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/colordistancesensor.rst

doc/ide/pupdevices/colorsensor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/colorsensor.rst

doc/ide/pupdevices/dcmotor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/dcmotor.rst

doc/ide/pupdevices/forcesensor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/forcesensor.rst

doc/ide/pupdevices/index.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/index.rst

doc/ide/pupdevices/infraredsensor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/infraredsensor.rst

doc/ide/pupdevices/light.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/light.rst

doc/ide/pupdevices/motor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/motor.rst

doc/ide/pupdevices/pfmotor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/pfmotor.rst

doc/ide/pupdevices/remote.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/remote.rst

doc/ide/pupdevices/tiltsensor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/tiltsensor.rst

doc/ide/pupdevices/ultrasonicsensor.rst

@@ -1 +0,0 @@
-.. include:: ../../api/pupdevices/ultrasonicsensor.rst

doc/ide/robotics.rst

@@ -1 +0,0 @@
-.. include:: ../api/robotics.rst

doc/ide/signaltypes.rst

@@ -1 +0,0 @@
-.. include:: ../api/signaltypes.rst

doc/ide/tools/datalog.rst

@@ -1,10 +0,0 @@
-Data logging
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. note::
-
-   This functionality is not yet available. It could be added
-   to Powered Up hubs in a future release. If you'd like to see this happen,
-   be sure to ask us on our `support page`_.
-
-.. _support page: https://github.com/pybricks/support/issues/

doc/ide/tools/index.rst

@@ -1 +0,0 @@
-.. include:: ../../api/tools/index.rst

doc/main/conf.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Pybricks documentation build configuration file
+#
+import os
+import sys
+
+# General information about the project.
+project = "pybricks"
+copyright = "2018-2021 The Pybricks Authors"
+author = ""
+
+_TITLE = "Pybricks Modules and Examples"
+_DISCLAIMER = "LEGO, the LEGO logo, MINDSTORMS and the MINDSTORMS EV3 logo are\
+               trademarks and/or copyrights of the LEGO Group of companies \
+               which does not sponsor, authorize or endorse this site."
+
+html_favicon = "../common/images/favicon.ico"
+html_logo = "../common/images/pybricks-logo-rtd.png"
+latex_logo = "../common/images/pybricks-logo-large.png"
+
+# Build main docs for RTD by default.
+# Since tags cannot be passed via the TAG make variable on read the docs,
+# add it manually.
+if os.environ.get("READTHEDOCS", None) == "True":
+    tags.add("main")  # noqa F821
+
+# HACK: this allows Number type alias to be imported by Sphinx
+os.environ["SPHINX_BUILD"] = "True"
+
+# Addtional configuration of the IDE docs
+if "ide" in tags.tags:  # noqa F821
+    _DISCLAIMER = ""
+    html_show_copyright = False
+    html_show_sphinx = False
+    html_css_files = ["css/ide.css"]
+    html_js_files = ["js/ide.js"]
+
+    imgmath_image_format = "svg"
+    imgmath_use_preview = True  # requires Sphinx v3
+    imgmath_latex_preamble = r"""
+    \usepackage{newtxsf}
+    """
+
+exec(open(os.path.abspath("../common/conf.py")).read())
+
+# Addtional configuration of the IDE docs
+if "ide" in tags.tags:  # noqa F821
+
+    extensions.remove("sphinx.ext.mathjax")  # noqa F821
+    extensions.append("sphinx.ext.imgmath")  # noqa F821
+    html_theme_options["prev_next_buttons_location"] = None  # noqa F821
+
+# Build hub specific example scripts.
+sys.path.append(os.path.abspath("../../examples/pup/hub_common"))
+import make_examples  # noqa F401, E402

doc/main/diagram_source/compat_cityhub_false.svg

@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_cityhub_false.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="3.5527137e-15"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/cityhub.png"
+       xlink:href="../images/cityhub.png"
+       style="stroke-width:5.6583333"
+       width="30.908323"
+       height="31.75"
+       preserveAspectRatio="none"
+       id="image1470"
+       x="5.2042809"
+       y="263.16479" />
+    <g
+       id="g862"
+       transform="matrix(0.84064533,0,0,0.84993509,-12.416361,243.07822)"
+       style="stroke-width:1.18304348">
+      <path
+         inkscape:connector-curvature="0"
+         id="path856"
+         d="m 51.33389,24.998882 5.622395,5.622396"
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="M 56.956285,24.998882 51.33389,30.621278"
+         id="path858"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>

doc/main/diagram_source/compat_cityhub_true.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_cityhub_true.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="4.4408921e-16"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/cityhub.png"
+       xlink:href="../images/cityhub.png"
+       style="stroke-width:5.6583333"
+       width="30.908323"
+       height="31.75"
+       preserveAspectRatio="none"
+       id="image1470"
+       x="5.2042809"
+       y="263.16479" />
+    <path
+       style="fill:none;stroke:#84ba4c;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 31.147057,265.82725 1.011052,2.9815 3.622948,-4.60003"
+       id="path854"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>

doc/main/diagram_source/compat_inventorhub_false.svg

@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_inventorhub_false.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="0"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/inventorhub.png"
+       xlink:href="../images/inventorhub.png"
+       style="stroke-width:5.92592621"
+       width="34.915073"
+       height="35.71875"
+       preserveAspectRatio="none"
+       id="image1481"
+       x="2.6458333"
+       y="261.28122" />
+    <g
+       id="g862"
+       transform="matrix(0.84064533,0,0,0.84993509,-12.416361,243.07822)"
+       style="stroke-width:1.18304348">
+      <path
+         inkscape:connector-curvature="0"
+         id="path856"
+         d="m 51.33389,24.998882 5.622395,5.622396"
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="M 56.956285,24.998882 51.33389,30.621278"
+         id="path858"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>

doc/main/diagram_source/compat_inventorhub_true.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_inventorhub_true.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="3.5527137e-15"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/inventorhub.png"
+       xlink:href="../images/inventorhub.png"
+       style="stroke-width:5.92592621"
+       width="34.915073"
+       height="35.71875"
+       preserveAspectRatio="none"
+       id="image1481"
+       x="2.6458333"
+       y="261.28122" />
+    <path
+       style="fill:none;stroke:#84ba4c;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 31.147057,265.82725 1.011052,2.9815 3.622948,-4.60003"
+       id="path854"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>

doc/main/diagram_source/compat_movehub_false.svg

@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_movehub_false.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="3.5527137e-15"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/movehub.png"
+       xlink:href="../images/movehub.png"
+       transform="translate(25.390602,-51.6498)"
+       clip-path="url(#clipPath1545)"
+       style="stroke-width:5.92592621"
+       width="40.183594"
+       height="35.71875"
+       preserveAspectRatio="none"
+       id="image1492"
+       x="-25.506657"
+       y="312.93103" />
+    <g
+       id="g862"
+       transform="matrix(0.84064533,0,0,0.84993509,-12.416361,243.07822)"
+       style="stroke-width:1.18304348">
+      <path
+         inkscape:connector-curvature="0"
+         id="path856"
+         d="m 51.33389,24.998882 5.622395,5.622396"
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="M 56.956285,24.998882 51.33389,30.621278"
+         id="path858"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>

doc/main/diagram_source/compat_movehub_true.svg

@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_movehub_true.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="69.775738"
+     inkscape:cy="79.243654"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="7.1054274e-15"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/movehub.png"
+       xlink:href="../images/movehub.png"
+       transform="translate(25.390602,-51.6498)"
+       clip-path="url(#clipPath1545)"
+       style="stroke-width:5.92592621"
+       width="40.183594"
+       height="35.71875"
+       preserveAspectRatio="none"
+       id="image1492"
+       x="-25.506657"
+       y="312.93103" />
+    <path
+       style="fill:none;stroke:#84ba4c;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 31.147057,265.82725 1.011052,2.9815 3.622948,-4.60003"
+       id="path854"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>

doc/main/diagram_source/compat_primehub_false.svg

@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_primehub_false.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="0"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/primehub.png"
+       xlink:href="../images/primehub.png"
+       style="stroke-width:5.92592621"
+       width="34.915073"
+       height="35.71875"
+       preserveAspectRatio="none"
+       id="image1503"
+       x="2.6458333"
+       y="261.28122" />
+    <g
+       id="g862"
+       transform="matrix(0.84064533,0,0,0.84993509,-12.416361,243.07822)"
+       style="stroke-width:1.18304348">
+      <path
+         inkscape:connector-curvature="0"
+         id="path856"
+         d="m 51.33389,24.998882 5.622395,5.622396"
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="M 56.956285,24.998882 51.33389,30.621278"
+         id="path858"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>

doc/main/diagram_source/compat_primehub_true.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_primehub_true.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="0"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/primehub.png"
+       xlink:href="../images/primehub.png"
+       style="stroke-width:5.92592621"
+       width="34.915073"
+       height="35.71875"
+       preserveAspectRatio="none"
+       id="image1503"
+       x="2.6458333"
+       y="261.28122" />
+    <path
+       style="fill:none;stroke:#84ba4c;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 31.147057,265.82725 1.011052,2.9815 3.622948,-4.60003"
+       id="path854"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>

doc/main/diagram_source/compat_technichub_false.svg

@@ -0,0 +1,104 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_technichub_false.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="10.681815"
+     inkscape:cy="89.597718"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1172"
+     inkscape:window-x="1920"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="0"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/technichub.png"
+       xlink:href="../images/technichub.png"
+       style="stroke-width:5.92592621"
+       width="35.71875"
+       height="35.71875"
+       preserveAspectRatio="none"
+       id="image1514"
+       x="2.1503351"
+       y="261.28122" />
+    <g
+       id="g862"
+       transform="matrix(0.84064533,0,0,0.84993509,-12.416361,243.07822)"
+       style="stroke-width:1.18304348">
+      <path
+         inkscape:connector-curvature="0"
+         id="path856"
+         d="m 51.33389,24.998882 5.622395,5.622396"
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+      <path
+         style="fill:none;stroke:#e2302f;stroke-width:1.18304348;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         d="M 56.956285,24.998882 51.33389,30.621278"
+         id="path858"
+         inkscape:connector-curvature="0" />
+    </g>
+  </g>
+</svg>

doc/main/diagram_source/compat_technichub_true.svg

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="150"
+   height="135"
+   viewBox="0 0 39.687499 35.718751"
+   version="1.1"
+   id="svg887"
+   inkscape:version="0.92.3 (2405546, 2018-03-11)"
+   sodipodi:docname="compat_technichub_true.svg">
+  <defs
+     id="defs881">
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath1545">
+      <rect
+         style="fill:#fe2020;fill-opacity:0.48022599;stroke:none;stroke-width:0.99999994;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+         id="rect1547"
+         width="39.6875"
+         height="35.71875"
+         x="-25.390602"
+         y="312.93103" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#fcfcfc"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="1"
+     inkscape:pageshadow="2"
+     inkscape:zoom="3.959798"
+     inkscape:cx="51.592993"
+     inkscape:cy="94.901019"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1853"
+     inkscape:window-height="1145"
+     inkscape:window-x="67"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1"
+     inkscape:snap-global="false" />
+  <metadata
+     id="metadata884">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-261.28123)">
+    <rect
+       style="fill:#fcfcfc;fill-opacity:1;stroke:none;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;paint-order:normal"
+       id="rect819"
+       width="39.6875"
+       height="35.71875"
+       x="0"
+       y="261.28122" />
+    <image
+       sodipodi:absref="../images/technichub.png"
+       xlink:href="../images/technichub.png"
+       y="261.28122"
+       x="2.1503351"
+       id="image1514"
+       preserveAspectRatio="none"
+       height="35.71875"
+       width="35.71875"
+       style="stroke-width:5.92592621" />
+    <path
+       style="fill:none;stroke:#84ba4c;stroke-width:1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="m 31.147057,265.82725 1.011052,2.9815 3.622948,-4.60003"
+       id="path854"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>