Examples: Add proper Table of Contents #20957

AnnsAnns · 2024-11-06T16:14:40Z

Contribution description

Currently there is no description of the examples (Some not even having a README).

This PR aims to add a basic table of contents README for the examples directory to improve the UX when searching for examples while also adding a few minor READMEs for undocumented examples.

It also tries to improve the general readability of the folder by categorizing examples into easier to digest categories within the README. This makes specific examples easier to find.

Testing procedure

There are no changes within this PR that would affect the code.

Issues/PRs references

This aims to help with some of the issues mentioned within #20388

riot-ci · 2024-11-07T09:13:30Z

Murdock results

✔️ PASSED

6f19763 examples/readme: Add subfolders example to categories

Success	Failures	Total	Runtime
1	0	1	01m:27s

Artifacts

Documentation preview

Teufelchen1

Didn't have time to do a throughout review but already found little issues.

examples/README.md

examples/pio_blink/README.md

examples/telnet_server/README.md

AnnsAnns

Will improve things mentioned, thank you for the review :)

examples/telnet_server/README.md

leandrolanzieri · 2024-11-08T08:42:50Z

@AnnsAnns do you think it would be possible to include a basic static test that goes over the directory list in examples and checks that at least they're mentioned in the README.md? I'm afraid this index can age if not enforced somehow...

mguetschow

Thanks for your work on this! Just had a brief look and left some comments below.

Could we maybe have a two-column table-style of the list? At least, I would argue for moving the explanation from the single subitem to the item itself, potentially after a colon (:).

examples/README.md

examples/telnet_server/README.md

examples/timer_periodic_wakeup/README:md

krzysztof-cabaj

I think that there is a little typo for timer_periodic_wakeup and this file should be named README.md not README:md (period instead of colon).

AnnsAnns · 2024-11-12T08:22:55Z

@AnnsAnns do you think it would be possible to include a basic static test that goes over the directory list in examples and checks that at least they're mentioned in the README.md? I'm afraid this index can age if not enforced somehow...

Looking into it, should be feasible :)

AnnsAnns · 2024-11-12T09:34:10Z

@AnnsAnns do you think it would be possible to include a basic static test that goes over the directory list in examples and checks that at least they're mentioned in the README.md? I'm afraid this index can age if not enforced somehow...

Added (Even found a few missing entries thanks to it 😅)

AnnsAnns · 2024-11-12T09:54:47Z

I hope I covered all mentioned issues, let me know if there is anything else :)

I also changed it to a table format as mentioned by @mguetschow, it definitely looks better on github

Teufelchen1 · 2024-11-12T12:12:21Z

Nice! I am happy with it. There's one static test that you should fix. A nit pick could be to combine the two ci tests into one, reducing the burden on the servers but I believe that is not significant here.

mguetschow

Looks good, thank you!

mguetschow · 2024-11-12T14:00:52Z

Would you mind squashing the commits together?

examples: ToC about all examples examples: Fix whiteline issues examples: Improve wording of Rust example Co-authored-by: Teufelchen <[email protected]> examples: Reduce redundant wording Co-authored-by: Teufelchen <[email protected]> examples: remove mention of repository Co-authored-by: Teufelchen <[email protected]> examples: Improve wording of coap example text Co-authored-by: Teufelchen <[email protected]>

examples/readme: fix SAUL spelling mistake examples/readme: Link to README.md instead of folder examples/readme: increase title size examples/readme: make networking category name a bit clearer examples/readme: move nimble to own category within BLE examples/readme: move dtls to own category examples/readme: move heart rate sensor to nimble category examples/readme: move arduino sketch to languages examples/timer_periodic: fix file name issue examples/readme: change level wording about nanocoap

examples/readme: add missing entries examples: document examples with no readme

mguetschow · 2024-11-12T15:37:14Z

Did you maybe accidentally drop some commit?

./dist/tools/examples_check/check_has_readme.sh x
  Command output:
  
  	The following directories are missing a README:
  	- pio_blink
  
./dist/tools/examples_check/check_in_readme.sh x
  Command output:
  
  	The following directories are missing in the README.md file:
  	- sock_tcp_echo

examples: Remove whitespace to fix CI

AnnsAnns · 2024-11-12T15:40:00Z

Did you maybe accidentally drop some commit?

./dist/tools/examples_check/check_has_readme.sh x
  Command output:
  
  	The following directories are missing a README:
  	- pio_blink
  
./dist/tools/examples_check/check_in_readme.sh x
  Command output:
  
  	The following directories are missing in the README.md file:
  	- sock_tcp_echo

Fixed, sock_tcp_echo was a new example (and pio_blink went missing)

mguetschow · 2024-11-13T13:35:17Z

@AnnsAnns we've merged a new example just today with #20024, and your CI check rightfully noticed that. Would you mind adding it to the table of content?

AnnsAnns · 2024-11-13T14:06:09Z

@AnnsAnns we've merged a new example just today with #20024, and your CI check rightfully noticed that. Would you mind adding it to the table of content?

Done

Teufelchen1 · 2024-11-14T09:04:14Z

Congrats! It's really awesome!

AnnsAnns requested a review from jia200x as a code owner November 6, 2024 16:14

github-actions bot added Area: doc Area: Documentation Area: examples Area: Example Applications labels Nov 6, 2024

benpicco requested a review from Teufelchen1 November 6, 2024 16:52

mguetschow added the CI: ready for build If set, CI server will compile all applications for all available boards for the labeled PR label Nov 7, 2024

Teufelchen1 requested changes Nov 7, 2024

View reviewed changes

AnnsAnns commented Nov 7, 2024

View reviewed changes

examples/telnet_server/README.md Show resolved Hide resolved

mguetschow requested changes Nov 8, 2024

View reviewed changes

krzysztof-cabaj reviewed Nov 9, 2024

View reviewed changes

github-actions bot added the Area: tools Area: Supplementary tools label Nov 12, 2024

AnnsAnns requested review from Teufelchen1 and mguetschow November 12, 2024 09:52

Teufelchen1 approved these changes Nov 12, 2024

View reviewed changes

mguetschow approved these changes Nov 12, 2024

View reviewed changes

mguetschow added this pull request to the merge queue Nov 12, 2024

mguetschow removed this pull request from the merge queue due to a manual request Nov 12, 2024

AnnsAnns and others added 2 commits November 12, 2024 16:17

AnnsAnns force-pushed the examples/readme branch from 688a8fa to a7e8c32 Compare November 12, 2024 15:24

ci: Add tests for examples folder

83e93a5

examples/readme: add missing entries examples: document examples with no readme

examples/readme: switch to tableformat

cd076d4

examples: Remove whitespace to fix CI

AnnsAnns force-pushed the examples/readme branch from a7e8c32 to cd076d4 Compare November 12, 2024 15:39

mguetschow added this pull request to the merge queue Nov 13, 2024

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Nov 13, 2024

examples/readme: Add subfolders example to categories

6f19763

Teufelchen1 enabled auto-merge November 13, 2024 14:12

Teufelchen1 added this pull request to the merge queue Nov 13, 2024

Merged via the queue into RIOT-OS:master with commit 03b6122 Nov 14, 2024
25 checks passed

miri64 mentioned this pull request Nov 26, 2024

check_in_readme.sh: tell dev _which_ README.md #21044

Merged

AnnsAnns mentioned this pull request Jan 14, 2025

examples: restructure examples folder #21135

Merged

MrKevinWeiss added this to the Release 2025.01 milestone Jan 20, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Examples: Add proper Table of Contents #20957

Examples: Add proper Table of Contents #20957

AnnsAnns commented Nov 6, 2024

riot-ci commented Nov 7, 2024 •

edited

Loading

Teufelchen1 left a comment

AnnsAnns left a comment

leandrolanzieri commented Nov 8, 2024

mguetschow left a comment

krzysztof-cabaj left a comment •

edited

Loading

AnnsAnns commented Nov 12, 2024

AnnsAnns commented Nov 12, 2024

AnnsAnns commented Nov 12, 2024 •

edited

Loading

Teufelchen1 commented Nov 12, 2024

mguetschow left a comment

mguetschow commented Nov 12, 2024

mguetschow commented Nov 12, 2024

AnnsAnns commented Nov 12, 2024 •

edited

Loading

mguetschow commented Nov 13, 2024

AnnsAnns commented Nov 13, 2024

Teufelchen1 commented Nov 14, 2024

Examples: Add proper Table of Contents #20957

Examples: Add proper Table of Contents #20957

Conversation

AnnsAnns commented Nov 6, 2024

Contribution description

Testing procedure

Issues/PRs references

riot-ci commented Nov 7, 2024 • edited Loading

Murdock results

Artifacts

Teufelchen1 left a comment

Choose a reason for hiding this comment

AnnsAnns left a comment

Choose a reason for hiding this comment

leandrolanzieri commented Nov 8, 2024

mguetschow left a comment

Choose a reason for hiding this comment

krzysztof-cabaj left a comment • edited Loading

Choose a reason for hiding this comment

AnnsAnns commented Nov 12, 2024

AnnsAnns commented Nov 12, 2024

AnnsAnns commented Nov 12, 2024 • edited Loading

Teufelchen1 commented Nov 12, 2024

mguetschow left a comment

Choose a reason for hiding this comment

mguetschow commented Nov 12, 2024

mguetschow commented Nov 12, 2024

AnnsAnns commented Nov 12, 2024 • edited Loading

mguetschow commented Nov 13, 2024

AnnsAnns commented Nov 13, 2024

Teufelchen1 commented Nov 14, 2024

riot-ci commented Nov 7, 2024 •

edited

Loading

krzysztof-cabaj left a comment •

edited

Loading

AnnsAnns commented Nov 12, 2024 •

edited

Loading

AnnsAnns commented Nov 12, 2024 •

edited

Loading