googleapis / googleapis/google-cloud-rust

Use feature gates instead of ignore tag for samples

Open
#5,500 0 comments 1 reaction 0 assignees View on GitHub
documentation samples type: cleanup
Dominant language
Rust
Stars
955
Forks
144
Avg merge
1d 5h
Merged PRs (30d)
279

Description

Using the \`\`\`ignore tag for samples renders docs with a warning that "this code is not tested".

Instead, we can feature gate the code in the sample, e.g.:

```rs
/// ```
/// # #[cfg(feature = "run_all_samples")]
/// # async fn sample() -> anyhow::Result<()> { ... }
/// ```
```

And build/run all the samples with `cargo test --doc --features run_all_samples`

https://github.com/googleapis/google-cloud-rust/blob/562640dd4d223edd11fd5839a7c9e0eedf146cdd/.gcb/scripts/test-ignored-samples.sh#L32

This also would let us reclaim the \`\`\`ignore tag for samples that are Rust code, but may or may not compile. Currently we use \`\`\`no_rust for this case as a workaround. Note that this is not a big win, as no public docs are affected. It just seems more correct to me.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.