Updated for various Sphinx API changes.
Also drop rendered math. Simpler and makes the plain Python docstrings look better in jedi.
```
:math:`0 \leq x \leq 255`.
```
just becomes 0 ≤ x ≤ 255.
Also drop Latex dependencies. We don't rely on the PDF and don't need it for math anymore.
Some were omitted once EV3 in Pybricks 2.0 was dropped, but they will be included again to prepare for EV3 in Pybricks 4.0.
Enable for Powered UP where relevant, as with UARTDevice.
The sources are hosted on GitHub, so there is not additional information here. Also, the actual docstrings are included in the .py files.
See https://github.com/pybricks/support/issues/1559
The default style of using a grid with two columns wastes space when
displayed in a narrow pane, like in Pybricks Code. Using flex with
column direction makes it flow from top to bottom.
Fixes: https://github.com/pybricks/support/issues/832
Previously, all renders were created and added manually when a newly
supported device was added to the documentation.
This commit revisits all diagrams by creating them using a single
LDRAW multi-file part model and LPUB3D building instructions file.
This makes perspective and resolution consistent across all images, and
we could update them all at once if needed.
It also removes the background from all images so they can be used
with different documentation themes.
This will help us review the pages as we add typing to the documentation. Then they will be hidden again.
This commit can be cherry-picked later on if we ever enable NXT and EV3 content again.
Also remove pybricks.common.Light which isn't used anywhere.
pupdevices.Light is a standalone light that does not support animations or blinks, so don't inherit from this nonexistent class.
Also remove the ColorLight.reset() method which was never implemented.
This formats return types so they don't look like tuples:
int: deg
If we can figure out how these nodes work, we can create proper links
and maybe use italics for the units or a slightly different font color.
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.
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.
Laurens Valk
David Lechner
Pavel Lobodinský