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.
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.
This simplifies the table and reduces its size.
Also copy assets manually since Sphinx does not automatically copy
images to _images when used for custom directives.
This can be traced back to 0013a74d72 and 92e3735d63.
It was used to work around things like
sound.beeps(number)
Description
being incorrectly displayed as
classmethod sound.beeps(number)
Description
But the current version of sphinx appears to display this correctly even without the hack. We want to reduce the number of hacks because they tend to break updates (https://github.com/pybricks/pybricks-api/issues/69#issuecomment-879822417).
On the web, we want to be able to navigate between the various Pybricks
subdomains without opening new tabs. But Pybricks Code is treated as an
"app", we don't want links to open in Pybricks Code.
We have index pages for most modules now, which link to individual classes. It is helpful if these empty class headers are hyperlinks. This commit does just that.
For most sensors/devices so far this is not really necessary as the images are already hyperlinks. But this will become more useful as we start adding index pages like these for classes without images, such as parameters.
Building pdf was broken because of chinese characters in one of the
code snippets.
LaTeX stack exchange recommends use XeTeX engine instead but this
causes other formatting problems (like footer using wide font) so
just hacking this in for now.
This way, you don't go to another page if you accidentally click an image.
If someone really needs the original size, they can right click on the image and copy or just zoom in.
External link decorations are already enabled in the documentation
content, but the RTD theme doesn't extend this to the sidebar. This
copies the css from the RTD theme and adds it to the sidebar.
This makes it less of a surprise when you click on a link and find
yourself on a completely different website.
Intellisense in VS Code (both jedi and ms python language server) picks
up all imported names and suggests them with equal priority for
code completion. By adding a leading underscore, intellisense lists
these with a lower priority, so they don't get in the way.
Also rename from builtins to _common while we are touching this to
better reflect the intention of the module (it contains types shared
by multiple modules, not builtin types like int).
This removes versioneer for versioning. The version depends on the
pybricks-micropython version targeted so it doesn't make sense to use
automatic versioning here.
Laurens Valk
Pavel Lobodinský
David Lechner