Add code snippets for docs that get run by CI but aren't example projects

[gartaud]

This suggestion is generic, but is the result of looking at this specific page: https://docs.wpilib.org/en/stable/docs/software/hardware-apis/sensors/accelerometers-software.html

The fundamental problem is that WPILib evolves faster than the documentation, and code snippets are sometimes obsolete.

For example, at the end of the page linked above, the code snippet refers to "LinearDigitalFilter" which has since been superseded by "LinearFilter". Copying the code snippet will result in frustration as one will try to figure out in which package the class can be found.

If it were possible to jump from the code snippet to a full example on GitHub (of course assuming in that scenario that online access is available), then it would become fairly obvious that the code snippet is obsolete, and one could quickly copy code that is up to date.

Thanks.

[calcmogul]

We have examples built against the latest WPILib already:

https://github.com/wpilibsuite/allwpilib/tree/main/wpilibcExamples https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples

The problem is the docs code snippets don't make sense as full example projects, and they'd pollute the collection of existing examples in the allwpilib repo. We could make a separate repo of docs snippets, but those are often just snippets instead of something that can actually be compiled.

[gartaud]

I stand corrected. I somehow have never looked at all those examples.

Still, I see two issues:

1. the code snippet can sometimes be obsolete (as mentioned earlier)

2. the examples can be somewhat hard to find

For (2) let's say I am looking at https://docs.wpilib.org/en/stable/docs/software/hardware-apis/misc/addressable-leds.html

How would I know that a full example is available at https://github.com/wpilibsuite/allwpilib/tree/main/wpilibjExamples/src/main/java/edu/wpi/first/wpilibj/examples/addressableled without realizing that I could manually go to https://docs.wpilib.org/en/stable/docs/software/examples-tutorials/wpilib-examples.html and then browse to the list of examples with the hope I could find one that is relevant?

Why not directly link to the example from the relevant documentation page with a quick note stating that a full example if available on Github (online access required)?

Thanks!

[Starlight220]

In most cases there is a note with a link. I agree it's not very visible at times, and sometimes missing.

There is an attempt to RLI more, but as said, not always it's possible.

[sciencewhiz]

@Daltz333 i think this is an frc-docs issue not an allwpilib. The infrastructure exists in allwpilib, but is not always used in frc-docs.

[PeterJohnson]

Rather than a separate repo, I think it would be better to add a directory within allwpilib for these types of snippets that are not example projects, so they get built with CI but don’t clutter the vscode examples.