Unstable documentation proof of concept (#2628)

* Unstable documentation proof of concept

* Hide the red banner in esp-wifi documentation

* Changelog

esp-hal/CHANGELOG.md

@@ -24,6 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `timer::Timer` trait has three new methods, `wait`, `async_interrupt_handler` and `peripheral_interrupt` (#2586)
 - Configuration structs in the I2C, SPI, and UART drivers now implement the Builder Lite pattern (#2614)
 - Added `I8080::apply_config`, `DPI::apply_config` and `Camera::apply_config` (#2610)
+- Introduced the `unstable` feature which will be used to restrict stable APIs to a subset of esp-hal. (#2628)
 
 ### Changed
 

esp-hal/Cargo.toml

@@ -40,6 +40,7 @@ enumset                  = "1.1.5"
 esp-build                = { version = "0.1.0", path = "../esp-build" }
 esp-synopsys-usb-otg     = { version = "0.4.2", optional = true, features = ["fs", "esp32sx"] }
 fugit                    = "0.3.7"
+instability              = "0.3"
 log                      = { version = "0.4.22", optional = true }
 nb                       = "1.1.0"
 paste                    = "1.0.15"
@@ -152,6 +153,9 @@ octal-psram = []
 # This feature is intended for testing; you probably don't want to enable it:
 ci = ["defmt", "bluetooth"]
 
+# Enables APIs that are not stable and thus come with no stability guarantees.
+unstable = []
+
 [lints.clippy]
 mixed_attributes_style = "allow"
 

esp-hal/MIGRATING-0.22.md

@@ -1,5 +1,11 @@
 # Migration Guide from 0.22.x to v1.0.0-beta.0
 
+Starting with this release, unstable parts of esp-hal will be gated behind the `unstable` feature.
+The `unstable` feature itself is unstable, we might change the way we hide APIs without notice.
+Unstable APIs are not covered by semver guarantees, they may break even between patch releases.
+
+Please refer to the documentation to see which APIs are marked as unstable.
+
 ## DMA changes
 
 ### Accessing channel objects

esp-hal/src/gpio/mod.rs

@@ -1864,6 +1864,7 @@ where
     P: OutputPin,
 {
     /// Set the GPIO to output mode.
+    #[instability::unstable]
     pub fn set_as_output(&mut self) {
         self.pin.set_to_push_pull_output(private::Internal);
     }

esp-hal/src/lib.rs

@@ -1,5 +1,5 @@
 #![cfg_attr(
-    docsrs,
+    all(docsrs, not(not_really_docsrs)),
     doc = "<div style='padding:30px;background:#810;color:#fff;text-align:center;'><p>You might want to <a href='https://docs.esp-rs.org/esp-hal/'>browse the <code>esp-hal</code> documentation on the esp-rs website</a> instead.</p><p>The documentation here on <a href='https://docs.rs'>docs.rs</a> is built for a single chip only (ESP32-C6, in particular), while on the esp-rs website you can select your exact chip from the list of supported devices. Available peripherals and their APIs change depending on the chip.</p></div>\n\n<br/>\n\n"
 )]
 //! # Bare-metal (`no_std`) HAL for all Espressif ESP32 devices.
@@ -140,6 +140,7 @@
 #![allow(asm_sub_register, async_fn_in_trait, stable_features)]
 #![cfg_attr(xtensa, feature(asm_experimental_arch))]
 #![deny(missing_docs, rust_2018_idioms)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 #![no_std]
 
 // MUST be the first module

esp-metadata/src/lib.rs

@@ -237,6 +237,9 @@ impl Config {
 ///
 /// This is required to avoid triggering the unexpected-cfgs lint.
 fn define_all_possible_symbols() {
+    // Used by our documentation builds to prevent the huge red warning banner.
+    println!("cargo:rustc-check-cfg=cfg(not_really_docsrs)");
+
     for chip in Chip::iter() {
         let config = Config::for_chip(&chip);
         for symbol in config.all() {

esp-wifi/src/lib.rs

@@ -1,5 +1,5 @@
 #![cfg_attr(
-    docsrs,
+    all(docsrs, not(not_really_docsrs)),
     doc = "<div style='padding:30px;background:#810;color:#fff;text-align:center;'><p>You might want to <a href='https://docs.esp-rs.org/esp-wifi/'>browse the <code>esp-wifi</code> documentation on the esp-rs website</a> instead.</p><p>The documentation here on <a href='https://docs.rs'>docs.rs</a> is built for a single chip only (ESP32-C3, in particular), while on the esp-rs website you can select your exact chip from the list of supported devices. Available peripherals and their APIs might change depending on the chip.</p></div>\n\n<br/>\n\n"
 )]
 //! This documentation is built for the

hil-test/Cargo.toml

@@ -206,7 +206,7 @@ embedded-hal-async = "1.0.0"
 embedded-hal-nb    = "1.0.0"
 esp-alloc          = { path = "../esp-alloc", optional = true }
 esp-backtrace      = { path = "../esp-backtrace", default-features = false, features = ["exception-handler", "defmt", "semihosting"] }
-esp-hal            = { path = "../esp-hal", features = ["digest"], optional = true }
+esp-hal            = { path = "../esp-hal", features = ["digest", "unstable"], optional = true }
 esp-hal-embassy    = { path = "../esp-hal-embassy", optional = true }
 esp-wifi           = { path = "../esp-wifi", optional = true, features = ["wifi"] }
 portable-atomic    = "1.9.0"

qa-test/Cargo.toml

@@ -13,7 +13,7 @@ embedded-graphics  = "0.8.1"
 embedded-hal-async = "1.0.0"
 esp-alloc          = { path = "../esp-alloc" }
 esp-backtrace      = { path = "../esp-backtrace", features = ["exception-handler", "panic-handler", "println"] }
-esp-hal            = { path = "../esp-hal" }
+esp-hal            = { path = "../esp-hal", features = ["unstable"] }
 esp-hal-embassy    = { path = "../esp-hal-embassy" }
 esp-println        = { path = "../esp-println", features = ["log"] }
 lis3dh-async       = "0.9.3"

xtask/src/cargo.rs

@@ -1,6 +1,7 @@
 //! Tools for working with Cargo.
 
 use std::{
+    ffi::OsStr,
     path::Path,
     process::{Command, Stdio},
 };
@@ -17,6 +18,16 @@ pub enum CargoAction {
 
 /// Execute cargo with the given arguments and from the specified directory.
 pub fn run(args: &[String], cwd: &Path) -> Result<()> {
+    run_with_env::<[(&str, &str); 0], _, _>(args, cwd, [])
+}
+
+/// Execute cargo with the given arguments and from the specified directory.
+pub fn run_with_env<I, K, V>(args: &[String], cwd: &Path, envs: I) -> Result<()>
+where
+    I: IntoIterator<Item = (K, V)>,
+    K: AsRef<OsStr>,
+    V: AsRef<OsStr>,
+{
     if !cwd.is_dir() {
         bail!("The `cwd` argument MUST be a directory");
     }
@@ -30,6 +41,7 @@ pub fn run(args: &[String], cwd: &Path) -> Result<()> {
     let status = Command::new(get_cargo())
         .args(args)
         .current_dir(cwd)
+        .envs(envs)
         .stdout(Stdio::inherit())
         .stderr(Stdio::inherit())
         .stdin(Stdio::inherit())

xtask/src/lib.rs

@@ -137,7 +137,11 @@ pub fn build_documentation(workspace: &Path, package: Package, chip: Chip) -> Re
     log::debug!("{args:#?}");
 
     // Execute `cargo doc` from the package root:
-    cargo::run(&args, &package_path)?;
+    cargo::run_with_env(
+        &args,
+        &package_path,
+        [("RUSTDOCFLAGS", "--cfg docsrs --cfg not_really_docsrs")],
+    )?;
 
     let docs_path = windows_safe_path(
         &workspace