v3.1.0

This method was added in 30803fc.

.github/workflows/build.yml

@@ -1,7 +1,7 @@
 # This workflow will install Python dependencies, run tests and lint with a variety of Python versions
 # For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
 
-name: Python package
+name: Build Python package and docs
 
 on: [ push, pull_request ]
 
@@ -40,4 +40,4 @@ jobs:
         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/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/release-to-pypi.yml

@@ -0,0 +1,22 @@
+name: Release to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build_and_publish:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - uses: abatilo/actions-poetry@v2.0.0
+      with:
+        poetry-version: 1.1.6
+    - run: poetry install
+    - run: poetry build
+    - run: poetry publish
+      env:
+        POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}

.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

@@ -6,7 +6,7 @@
     "python.linting.enabled": true,
     "python.languageServer": "Pylance",
     "files.associations": {"*.inc": "restructuredtext"},
-    "restructuredtext.confPath": "${workspaceFolder}/doc/api",
+    "restructuredtext.confPath": "${workspaceFolder}/doc/main",
     "spellright.language": [
         "en_US"
     ],

CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+<!-- refer to https://keepachangelog.com/en/1.0.0/ for guidance -->
+
+## 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,20 +20,23 @@ 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
+- Use a prefix to categorize the change:
-  being changed. 
+  - Use the import path as the prefix whenever possible. Examples:
-  - If it is a documentation change, it can be shortened to `doc/<file>` (omit
+     - pybricks.tools: Add StopWatch class.
-    `api` from the path).
+     - pybricks.tools: Reorganize RST files.
-  - If it is an API change (in the `pybricks` folder), write `api/<file>` 
+     - pybricks.tools.StopWatch: Fix return type.
-    instead of `pybricks/<file>`.
+     - pybricks.tools.wait: Add example of waiting.
-- The subject briefly describes _what_ was changed, e.g. `fix typo`.
+     - 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
 
@@ -59,15 +62,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:
 

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) -t $(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/index.rst

@@ -1,51 +0,0 @@
-:mod:`hubs <pybricks.hubs>` -- Programmable Hubs
-================================================
-
-.. module:: pybricks.hubs
-
-.. toctree::
-   :maxdepth: 1
-   :hidden:
-
-   movehub
-   cityhub
-   technichub
-   primehub
-   ev3brick
-
-.. 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
-
-.. pybricks-classlink:: EV3Brick
-
-.. figure:: ../../api/images/ev3brick.png
-    :height: 10 em
-    :target: ev3brick.html
-

doc/api/hubs/technichub.rst

@@ -1,99 +0,0 @@
-Technic Hub
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. figure:: ../../api/images/technichub.png
-    :height: 15 em
-
-.. autoclass:: pybricks.hubs.TechnicHub
-    :no-members:
-
-    .. rubric:: Using the hub status light
-
-    .. automethod:: pybricks.hubs::TechnicHub.light.on
-
-    .. automethod:: pybricks.hubs::TechnicHub.light.off
-
-    .. automethod:: pybricks.hubs::TechnicHub.light.blink
-
-    .. automethod:: pybricks.hubs::TechnicHub.light.animate
-
-    .. rubric:: Using the IMU
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.up
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.tilt
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.acceleration
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.angular_velocity
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.heading
-
-    .. automethod:: pybricks.hubs::TechnicHub.imu.reset_heading
-
-    .. rubric:: Using the battery
-
-    .. automethod:: pybricks.hubs::TechnicHub.battery.voltage
-
-    .. automethod:: pybricks.hubs::TechnicHub.battery.current
-
-Status light examples
----------------------
-
-Turning the light on and off
-****************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/light_off.py
-
-Changing brightness and using custom colors
-*******************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/light_hsv.py
-
-Making the light blink
-**********************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/light_blink.py
-
-Creating light animations
-*************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/light_animate.py
-
-IMU examples
----------------
-
-Testing which way is up
-********************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_up.py
-
-
-Reading the tilt value
-********************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_tilt.py
-
-Using a custom hub orientation
-**************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_tilt_blast.py
-
-Reading acceleration and angular velocity vectors
-**************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_read_vector.py
-
-Reading acceleration and angular velocity on one axis
-*****************************************************
-
-.. literalinclude::
-    ../../../examples/pup/hub_technichub/imu_read_scalar.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,23 +0,0 @@
-Remote Control
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. warning::
-
-    This remote is not yet supported.
-    Upvote `this issue <https://github.com/pybricks/support/issues/186>`_ if
-    you want to see this happen.
-
-.. 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

doc/common/_static/js/ide.js

@@ -1,3 +1,4 @@
+// Since Pybricks Code is an "app", all external links get opened in new tab/window
 // https://stackoverflow.com/a/62742435/1976323
 $(document).ready(function () {
     $('a[href^="http://"], a[href^="https://"]').not('a[class*=internal]').attr('target', '_blank');

doc/common/conf.py

@@ -27,11 +27,10 @@ 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
 import toml
 
 TOP_DIR = os.path.abspath(os.path.join('..', '..'))
-sys.path.insert(0, TOP_DIR)
+sys.path.insert(0, os.path.join(TOP_DIR, 'src'))
 sys.path.append(os.path.abspath('../common/extensions'))
 
 from pybricks.hubs import EV3Brick  # noqa E402
@@ -60,6 +59,8 @@ extensions = [
     'sphinx.ext.mathjax',
     'color',
     'classlink',
+    'requirements',
+    'requirements-static',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -91,7 +92,7 @@ version = re.match(r'(v\d+\.\d+)', release)[0]
 language = None
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'xcode'
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
@@ -128,6 +129,20 @@ nitpick_ignore = [
     ('py:exc', 'ValueError'),
 ]
 
+# not sure why, but this is needed for typing.IO in uselect
+nitpick_ignore.append(('py:class', 'IO'))
+
+# Workaround until change below is released.
+# https://github.com/sphinx-doc/sphinx/commit/86091934db5ec593b4b0c982b7f08f3231ef995b
+nitpick_ignore.extend([
+    ('py:class', '0'),
+    ('py:class', '1'),
+    ('py:class', '2'),
+    ('py:class', '3'),
+    ('py:class', 'big'),
+    ('py:class', 'little'),
+])
+
 # -- Autodoc options ------------------------------------------------------
 
 autodoc_member_order = 'bysource'
@@ -147,11 +162,6 @@ else:
     html_theme = 'sphinx_rtd_theme'
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
-# a little extra javascript
-html_js_files = [
-    'js/custom.js'
-]
-
 html_context = {
     'disclaimer': _DISCLAIMER,
 }
@@ -249,7 +259,27 @@ latex_documents = [
      author, 'manual'),
 ]
 
-# -- Options for manual page output ---------------------------------------
+# -- Content control -----------------------------------------------------
+
+
+exclude_patterns = [
+    'ev3devices.rst',
+    'hubs/ev3brick.rst',
+    'hubs/primehub.rst',
+    'geometry.rst',
+    'iodevices/analogsensor.rst',
+    'iodevices/dcmotor.rst',
+    'iodevices/ev3devsensor.rst',
+    'iodevices/i2cdevice.rst',
+    'iodevices/lumpdevice.rst',
+    'iodevices/lwp3device.rst',
+    'iodevices/uartdevice.rst',
+    'media.rst',
+    'messaging.rst',
+    'nxtdevices.rst',
+    'tools/datalog.rst'
+]
+
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
@@ -295,44 +325,3 @@ def setup(app: Sphinx):
 
 
 # -- 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,13 +5,15 @@ 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()) +
+            '<a href="{0}.html">'.format(link.lower()) +
             '<dl class="py class">' +
             '<dt>' +
             '<em class="property">class </em>' +

doc/common/extensions/requirements-static.py

@@ -0,0 +1,101 @@
+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,
+}
+
+
+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/ide/CHANGELOG.md

@@ -1,20 +0,0 @@
-# 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,32 +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']
-
-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,43 +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
-
-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/

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,50 @@
+#!/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'
+
+# 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
+
+
+# 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

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>