Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ci(docs): render manufacturer-specific docs #531

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

ROMemories
Copy link
Collaborator

Description

This generates the rustdoc docs for the manufacturer-specific crates (MSCs) that were extracted as part of #392.
The doc page of the riot_rs::arch module provides the user with a "manual redirect" to the items relevant for the target MCU, provided by the MSCs.

The current state of the generated docs can be seen on my fork: https://romemories.github.io/RIOT-rs/dev/docs/api/riot_rs/arch/index.html

Limitations

The documentation of the MSCs are currently rendered for one MCU only (and that MCU is not currently mentioned in the docs). This is a significant limitation, but it's unclear how solve that in the general case (e.g., riot-rs-stm32 may end supporting 1400 different MCUs).

E.g., the nRF5340 also supports 250 kHz as an I2C frequency, but this does not currently appear in the docs because they are currently rendered for the nrf52840 only.

Issues/PRs references

This is the continuation of #392.

Open Questions

  • Should we attempt to find a solution to the limitation above or roll with it for now?
  • Additionally, all public types of the MSCs are part of these docs; some of them are definitely to be accessed by users (e.g., MCU-specific I2C Frequency types) but others are completely internal. We should agree on how we go about hiding those.

Change checklist

  • I have cleaned up my commit history and squashed fixup commits.
  • I have followed the Coding Conventions.
  • I have performed a self-review of my own code.
  • I have made corresponding changes to the documentation.

@ROMemories ROMemories added docs Improvements or additions to documentation CI arch Architecture support labels Nov 14, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
arch Architecture support CI docs Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant