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.

Sign up for GitHub

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

Jump to bottom

docs(book): add an initial version of the support matrix #324

Merged
merged 13 commits into from
Jul 10, 2024
Merged

docs(book): add an initial version of the support matrix #324

merged 13 commits into from
Jul 10, 2024

Conversation

ROMemories
Copy link
Collaborator

@ROMemories ROMemories commented Jun 21, 2024 •
edited
Loading

Description

This introduces a structured data file encoding current hardware and functionality support across supported chips and boards, along with a Cargo script generating HTML from this structured data. The generated HTML is written to a file which is imported into the book, providing comprehensive support information for potential users. That HTML file must be re-generated when the structured data file is updated, but a CI lint check makes sure that this HTML file is always up to date.

This support table covers hardware support as well as software/configuration support.

Limitations

This is mostly meant to bootstrap this compatibility table and support information definitely incomplete. It must still reflect the current state of support at the time of merge.

@kaspar030 Can you check the current state of debug output and logging, and the current ESP32 support?
@kaspar030 @elenaf9 If threading needs to be added to this table, please do so in a follow-up PR.
@chrysn Could you add HWRNG to this table in a follow-up PR?

  • The structured data file must currently be manually updated. Ideally we would leverage support information already encoded in the laze configuration to validate/invalidate that file.
  • This could also benefit from later introduced an intermediate level between chips and boards, e.g., chip_families.

Issues/PRs references

N/A

Open Questions

None

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 network arch Architecture support board Board support labels Jun 21, 2024
@kaspar030
Copy link
Collaborator

I think this is a great start! I hope we can make this auto-generated at some point - laze should have all info.

@kaspar030
Copy link
Collaborator

We use an HTML table as the GitHub Tables extension does not support cells spanning on multiple rows or columns.

Hm, I personally don't support hand-editing raw html tables. I'd prefer using a markdown table (and duplicating e.g., the rp2040 line)... wdyt?

@elenaf9 elenaf9 mentioned this pull request Jul 2, 2024
Open
18 tasks
@ROMemories ROMemories marked this pull request as draft July 2, 2024 09:22
@ROMemories
Copy link
Collaborator Author

Marking as draft for now as we agreed to generate this table from structured data instead.

@emmanuelsearch emmanuelsearch added this to the Next Release milestone Jul 2, 2024
@ROMemories ROMemories force-pushed the docs/initial-support-matrix branch 2 times, most recently from b875a84 to b46a9e7 Compare July 4, 2024 12:10
@ROMemories ROMemories marked this pull request as ready for review July 4, 2024 12:29
chrysn
chrysn reviewed Jul 4, 2024
View reviewed changes
Copy link
Collaborator

@chrysn chrysn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the structure. Makes me want to consider whether we can pioneer https://github.com/RIOT-OS/RIOT/blob/master/doc/memos/rdm0003.md in here.

doc/gen_support_matrix_html.rs Outdated Show resolved Hide resolved
doc/gen_support_matrix_html.rs Outdated Show resolved Hide resolved
doc/support_matrix.yml Outdated Show resolved Hide resolved
doc/gen_support_matrix_html.rs Outdated Show resolved Hide resolved
doc/support_matrix.yml Show resolved Hide resolved
doc/support_matrix.yml Outdated Show resolved Hide resolved
@kaspar030
Copy link
Collaborator

I like this a lot!

@ROMemories
Copy link
Collaborator Author

Makes me want to consider whether we can pioneer https://github.com/RIOT-OS/RIOT/blob/master/doc/memos/rdm0003.md in here.

Agree that a well-defined naming conventions for chips/boards wouldn't hurt. We would need to extend it to support families of chips as well (e.g., nRF52xxx) I think.

@kaspar030
Copy link
Collaborator

Some offline discussion notes:

  • too many "Key" options. reduce to "Supported ✅" , "(Supported) ☑️", "Not supported by RIOT-rs ❌", "Not supported by hardware (-)"

@kaspar030
Copy link
Collaborator

LGTM. please squash!

@kaspar030 kaspar030 enabled auto-merge July 10, 2024 08:18
@ROMemories
docs(book): add an initial version of the support matrix
2d763e8 
Generate a support table from structured data. This table covers
hardware support as well as software/configuration support.
This structured data file is meant to later be validated/invalidated
based on the laze configuration, so that it always reflects the current
state of support.
@ROMemories
feat(support-matrix): support checking whether the output file is out…
8acb8cc 
…dated

This is useful in CI: developers are responsible for generating the HTML
file, but it can be checked in CI that that output file is up to date.
@ROMemories
ci(support-matrix): check that the HTML support matrix is up to date
974f919
@ROMemories
feat(support-matrix): improve some error messages
99c4865
@ROMemories
fix(support-matrix): validate support keys for boards and chips
1d8e4dc
@ROMemories
docs(support-matrix): add some comments explaining the matrix's struc…
e3c46a1 
…ture
@ROMemories
refactor(support-matrix): rename supports to support
3fc51f5
@ROMemories
fix(support-matrix): make the definition of support keys ordered
43ae68b 
This is required so that we can control the order in which the keys are
shown in the HTML, and to be make sure the generation is deterministic.
@ROMemories
fix(support-matrix): leverage support inheritance where possible
66be237
@ROMemories
feat(support-matrix): allow arbitrary URLs as links
d71b8ac
@ROMemories
fix(support-matrix): use dl/dt/dd HTML elements for the table key
f66c8dc
@ROMemories
feat(support-matrix): document STM32 support
ccc6ca3
@ROMemories
fix(support-matrix): fix output sorting
79e354a
@kaspar030 kaspar030 added this pull request to the merge queue Jul 10, 2024
Merged via the queue into future-proof-iot:main with commit ce7b9e0 Jul 10, 2024
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@chrysn chrysn chrysn left review comments

@kaspar030 kaspar030 kaspar030 left review comments

Assignees
No one assigned
Labels
arch Architecture support board Board support docs Improvements or additions to documentation network
Projects
None yet
Milestone
Next Release
Development

Successfully merging this pull request may close these issues.
4 participants
@ROMemories @kaspar030 @chrysn @emmanuelsearch