Documentation improvements

[jessebraham]

There are a number of changes we would like to make to our documentation, so this will serve as a tracking issue (or an "epic", if you will) for each individual task.

If you would like to complete one of these tasks, please assign yourself to the issue if one already exists, or create a new issue and assign yourself to it.

• Generated documentation should include feature-gated APIs #992
  • Some discussion will need to be had which features (all?) should be enabled when building documentation.
• Investigate adding runnable doctests to peripheral drivers #1095
• Use the unstable doc_cfg feature to document which cargo features are required for modules/types/etc.
  • See espflash docs for example of this: https://docs.rs/espflash/latest/espflash/
  • Requires:
    • Package metadata: https://github.com/esp-rs/espflash/blob/main/espflash/Cargo.toml#L17-L18
    • Global attr: https://github.com/esp-rs/espflash/blob/main/espflash/src/lib.rs#L28
    • Per-module/-type attrs: https://github.com/esp-rs/espflash/blob/main/espflash/src/lib.rs#L30-L32
• Hosting multichip docs #1204
• Remove references to chip-specific HAL packages (if any remain)
• Avoid documenting features that don't apply to the current chip/cfg away (or add) chip specific documentation for drivers
• Update the CONTRIBUTING.md guide #1225
• Embassy main proc_macro doesn't have rustdoc for every generated element #1233
• The resources/index.html file should be converted to a template, and the packages and their versions should be populated dynamically. #1276
• It would be nice to list which peripherals are and aren't supported for each device
  • JB: This can probably be automated, will look into it
• We should be explicit about which drivers provide blocking and/or async APIs
  • JB: This can probably be automated, will look into it
• Be explicit about the need to build using the release profile #1261
• Some module level docs need a complete overhaul
  • interrupt module is too generic, and the example isn't correct. Improved via RISCV: remove the direct-vectoring & interrupt-preemption features and enable them by default #1310

[AnthonyGrondin]

Not sure where to drop this, but if we want to test for documentation coverage of the public APIs in CI, we could do something like:

cargo rustdoc -q -- -Z unstable-options --show-coverage | grep -i total | grep -oE '[0-9]*\.[0-9]*%' | head -n1 | grep -q 100.0%

1. Get lists of documentation coverage
2. Get the last line, "total"
3. Extract both percentage (doc, examples) from the line.
4. Get first one (doc)
5. Check if == 100%.

[bjoernQ]

We probably also want to double check what we want to hide from the docs

e.g. here: https://docs.rs/esp32s3-hal/0.15.0/esp32s3_hal/gpio/index.html - GpioXSignals is pretty much useless for users of the HAL

https://docs.rs/esp32s3-hal/0.15.0/esp32s3_hal/gpio/trait.GpioProperties.html - the whole trait is probably cryptic and useless for most users

Not a priority but always I look into the docs I think about this and quickly forget about then

[playfulFence]

Working on #1276