Previously, arguments had "types" like ":ref:`speed`", which would be rendered by Sphinx as a hyperlink and displayed as "rotational speed: deg/s".
This worked well enough but it had a few shortcomings:
- It looks bad on autocomplete, which doesn't know how to render RST with cross references.
- No real type information: int, float, ... ?
- Some units are very long, making the docs less concise.
- The unified approach doesn't always work. Some method arguments can be either deg/s or mm/s, depending on the application. This gets even lengthier.
- It's hard to maintain if you don't know what to link to.
In the new approach, the unit is just added to the type as plain text. Instead of giving the physical signal name, we give the real data type, which is more standard. The physical signal name is usually apparent from the docstring anyway, and can be inferred from the unit as well. This also solves all of the above problems.
Since most Pybricks methods allow both int and float for numeric inputs, we document these as a Number type, which is the union of int and float. Since the type is no longer directly tied to the type, we can still document the return type correctly, since this is never a union.
Instead of having complicated hacks in Sphinx to make this work (I have tried many), it turns out we can conveniently suppress broken references and still display the units. The only downside is that units will no longer have hyperlinks to the signal pages, at least for the moment. We should be able to make on_missing_reference a bit smarter to format the units as we see fit if needed.
The approach here is exemplified in the Motor.run_until_stalled method. Subsequent commits will apply it everywhere. Also clarify the behavior for duty_limit=None while we are updating this code anyway.
Fixes https://github.com/pybricks/pybricks-api/issues/94
For Move Hub, this is a breaking change since Move Hub IMU support
was already released. For the other hubs, the IMU API has not been
released yet, so we can do this silently.
Prior to every previous release, we we had to delete certain
features that did not make it into the release. This lets us
do that with a tag instead. This way we can keep a clean git
history that is easier to follow.
Version tags can be useful to keep track of new or updated features.
This lets us hide such details in the documentation that ships with the IDE to keep it concise.
We were not using a proper release for sphinx-rtd-theme
in order to work around some bugs. Meanwhile, a proper
release has come out, so let's upgrade to 1.0.0.
Also bump Sphinx to 4.4.
Also update and fix workarounds for cross references.
Fixes https://github.com/pybricks/pybricks-api/issues/98.
- Use isometric projection
- Fix broken plug
- Use correct background color
While we are at it, add colors to show which 9 colors this device supports.
This splits the Sphinx tag option from SPHINXOPTS. This allows us to
specify the tag without having to remember to add -W and -t. It also
fixes not being able to specify the tag with make.bat on Windows.
While we are touching this, redundant SOURCEDIR uses are removed (main
is already the default) and the .github/workflows/publish-ide-docs.yml
script is fixed (ide directory no longer exists).
This way we can do the following, which is useful if it cannot be expressed in terms of other requirements.
.. pybricks-requirements:: movehub
A good example is on the specific hub page itself. The Move Hub requires the Move Hub.
We will work on a version that can be toggled dynamically. It will just include this static version. This keeps things simple and still lets
us use the static version as needed.
Laurens Valk
Pavel Lobodinský
David Lechner