Follow up for fixing axis convention

[peter-mitrano-ar]

• updates examples to use the HID_Z_UP convention
• rework the last two examples showing how custom configs and axes inversion works
• update docs to avoid copy pasting

Summary by Sourcery

Align examples and documentation with the HID_Z_UP axis convention and improve guidance on custom device configurations.

New Features:

• Add a Unity-convention custom device configuration example demonstrating fully custom device specs and mappings.
• Add an example demonstrating how to invert rotation axes using device specs and axis conventions.

Enhancements:

• Update existing examples to explicitly use the HID_Z_UP axis convention where appropriate.
• Restructure mouse API examples documentation to list, describe, and auto-include example scripts via snippets.
• Clarify README example descriptions to distinguish rotation inversion from fully custom Unity-style configs.
• Reorder axis convention diagrams in the docs for clearer emphasis on the HID_Z_UP convention.
• Update contributing guidelines to require keeping example listings in README and mouse API docs in sync.
• Enable MkDocs snippets extension to support including external example files in documentation.

Documentation:

• Revamp the mouse API examples page to link to numbered example scripts with summaries and embedded code snippets.

[sourcery-ai]

Hey - I've left some high level feedback:

• In 10_custom_config_unity.py, the hard-coded VID/PID and axis mappings are specific to one device model; consider either deriving from an existing get_device_specs() entry or adding a short comment warning users to adjust these values to match their own device to avoid confusing misconfigurations.
• The internal titles like Example 2: / Example 3: in the new example scripts can easily drift from the numbered filenames (09/10); it may be clearer to remove the embedded example numbers or derive them from __file__ so they stay in sync with the docs and filenames.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `10_custom_config_unity.py`, the hard-coded VID/PID and axis mappings are specific to one device model; consider either deriving from an existing `get_device_specs()` entry or adding a short comment warning users to adjust these values to match their own device to avoid confusing misconfigurations.
- The internal titles like `Example 2:` / `Example 3:` in the new example scripts can easily drift from the numbered filenames (09/10); it may be clearer to remove the embedded example numbers or derive them from `__file__` so they stay in sync with the docs and filenames.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[peter-mitrano-ar]

@nickswalker if you have time for a quick review here too, I would appreciate it :)

[nickswalker]

The use case for allowing users to write their own device specs makes sense (future/custom hardware), but I think you'd want users to not need to use this low level interface for changing the axis convention. It would be easy to mess up incidentally e.g. having an incorrect digit for a byte offset someplace. In that spirit, would simply have this example show how a user could've added SpaceMouseWirelessNew themselves (with the same info from device.toml).

The Unity convention is a reasonable use case though, so it would make sense to support it natively, but it'd require the modify_device_info() method to have the ability to remap axes altogether.

[nickswalker]

Another thought: it may actually be desirable to "require" devices to be specified in the HID convention, that way the library knows how to remap the axes.

[peter-mitrano-ar]

Currently they are all specified in "LEGACY" convention, so we already know how to remap axes to a given convention, right? We could change everything to be HID in the TOML, as long as we still offer LEGACY as an option.

[nickswalker]

Changing the TOML may break existing uses, as the specs data is part of the public API (pyspacemouse.get_device_specs()["SpaceNavigator"]). I think the TOML should definitely change over to HID in the next major release.

[nickswalker]

I think the new example 10 actually suggests some further API changes/enhancements. The bulk of the changes look good to me otherwise.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.