Enhance Spin SDK rust docs with examples

[kate-goldenring]

We have published our Rust SDK to Rust docs; however, i still find myself searching Spin docs (https://developer.fermyon.com/spin/v3/index) to make sure i am using SDKs correctly. Instead, i'd like the Rust SDK crates docs to be my main source of information for how to use the SDK. For example, if I want to open and write to a key value store, i'd like to see an example in the rust docs here https://docs.rs/spin-sdk/3.1.0/spin_sdk/key_value/struct.Store.html.

[itowlson]

Vague notes as I noodle on this:

• Some key items are generated from WIT (e.g. per Kate's example spin_sdk::key_value::Store). I am not sure if cargo doc provides a way to attach Rust-specific docs to such things. Of course, we can put them in key_value module docs, but readers on the Store page of the docs won't see them. (ETA: ah Store is re-exported so we can probably inject docs at that point althought that still doesn't provide a way to add examples to methods.) (ETA: partial result. Docs on the re-export are prepended to the WIT doc string.)

• I am not sure how to validate example code. Normally one could use cargo test --doc, but for Spin SDK examples this fails because the main function is unsuitable and the test host doesn't provide the API. (Yes, cargo test has a --no-run option... but you aren't allowed to use it with --doc.) SOLVED: use the no_run decoration on the backticks. https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html#attributes

• I can't find a way to validate examples decorated with #[http_component] in the examples. The compilation fails with "cannot find function handle_all_the_things in module super". I can either ignore them (the example won't be checked) or skip the macro (the example will be checked, but a reader who copies the example directly won't get the entry point behaviour). I'm not sure which is the lesser evil. (ETA: the ignore flag puts up a nasty orange info tip in the rendered docs saying "this example is not tested" which is causing me to have OPINIONS as to which is the lesser evil.)

[itowlson]

The WIT docs getting appended got a but unpleasant on the Fields type, with stuff about "the following block" which makes no sense when surfaced in rustdoc. My fix is to do something that looks very silly in source:

but at least contextualises the weirdness in rendered:

[kate-goldenring]

but at least contextualises the weirdness in rendered:

I like it!