Use relevant features when building documentation (#2295)

* Use relevant features when building documentation

* CHANGELOG.md and migration guide

* Fix imports

esp-wifi/CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - esp-wifi now allocates memory from the global allocator provided by `esp-alloc` (#2099)
 - Renamed the `wifi-logs` feature to `sys-logs` for consistency (#2183)
 - Updated drivers to v5.3.1 (#2239)
+- Rename `initialize` to `init` (#2295)
 
 ### Fixed
 

esp-wifi/Cargo.toml

@@ -5,6 +5,7 @@ edition = "2021"
 rust-version  = "1.79.0"
 authors = ["The ESP-RS team"]
 description = "A WiFi, Bluetooth and ESP-NOW driver for use with Espressif chips and bare-metal Rust"
+documentation = "https://docs.esp-rs.org/esp-hal/"
 repository = "https://github.com/esp-rs/esp-hal"
 license = "MIT OR Apache-2.0"
 

esp-wifi/MIGRATING-0.9.md

@@ -2,7 +2,7 @@
 
 ## Initialization
 
-You no longer have to set up clocks and pass them to `esp_wifi::initialize`.
+You no longer have to set up clocks and pass them to `esp_wifi::init` and the `esp_wifi:initialize` function is renamed to `esp_wifi::init`.
 
 ```diff
  use esp_hal::{
@@ -25,7 +25,8 @@ You no longer have to set up clocks and pass them to `esp_wifi::initialize`.
 
      let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-     let init = initialize(
+-     let init = initialize(
++     let init = init(
          EspWifiInitFor::Wifi,
          timg0.timer0,
          Rng::new(peripherals.RNG),

esp-wifi/src/lib.rs

@@ -1,3 +1,7 @@
+#![cfg_attr(
+    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
 #![cfg_attr(esp32, doc = "**ESP32**")]
 #![cfg_attr(esp32s2, doc = "**ESP32-S2**")]
@@ -387,7 +391,7 @@ impl EspWifiTimerSource for TimeBase {
 /// use esp_wifi::EspWifiInitFor;
 ///
 /// let timg0 = TimerGroup::new(peripherals.TIMG0);
-/// let init = esp_wifi::initialize(
+/// let init = esp_wifi::init(
 ///     EspWifiInitFor::Wifi,
 ///     timg0.timer0,
 ///     Rng::new(peripherals.RNG),
@@ -396,7 +400,7 @@ impl EspWifiTimerSource for TimeBase {
 /// .unwrap();
 /// # }
 /// ```
-pub fn initialize(
+pub fn init(
     init_for: EspWifiInitFor,
     timer: impl EspWifiTimerSource,
     rng: hal::rng::Rng,

examples/src/bin/wifi_80211_tx.rs

@@ -18,7 +18,7 @@ use esp_hal::{
     rng::Rng,
     timer::{timg::TimerGroup, AnyTimer, PeriodicTimer},
 };
-use esp_wifi::{initialize, wifi, EspWifiInitFor};
+use esp_wifi::{init, wifi, EspWifiInitFor};
 use ieee80211::{
     common::{CapabilitiesInformation, FCFFlags},
     element_chain,
@@ -49,7 +49,7 @@ fn main() -> ! {
     let timer0: AnyTimer = timg0.timer0.into();
     let timer = PeriodicTimer::new(timer0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timer,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_access_point.rs

@@ -20,7 +20,7 @@ use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::{print, println};
 use esp_wifi::{
     current_millis,
-    initialize,
+    init,
     wifi::{
         utils::create_network_interface,
         AccessPointConfiguration,
@@ -45,7 +45,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_access_point_with_sta.rs

@@ -21,7 +21,7 @@ use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::{print, println};
 use esp_wifi::{
     current_millis,
-    initialize,
+    init,
     wifi::{
         utils::{create_ap_sta_network_interface, ApStaInterface},
         AccessPointConfiguration,
@@ -52,7 +52,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_bench.rs

@@ -20,7 +20,7 @@ use esp_hal::{delay::Delay, prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::println;
 use esp_wifi::{
     current_millis,
-    initialize,
+    init,
     wifi::{
         utils::create_network_interface,
         AccessPointInfo,
@@ -64,7 +64,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_ble.rs

@@ -31,7 +31,7 @@ use esp_hal::{
     timer::timg::TimerGroup,
 };
 use esp_println::println;
-use esp_wifi::{ble::controller::BleConnector, initialize, EspWifiInitFor};
+use esp_wifi::{ble::controller::BleConnector, init, EspWifiInitFor};
 
 #[entry]
 fn main() -> ! {
@@ -46,7 +46,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Ble,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_coex.rs

@@ -32,7 +32,7 @@ use esp_println::{print, println};
 use esp_wifi::{
     ble::controller::BleConnector,
     current_millis,
-    initialize,
+    init,
     wifi::{utils::create_network_interface, ClientConfiguration, Configuration, WifiStaDevice},
     wifi_interface::WifiStack,
     EspWifiInitFor,
@@ -76,7 +76,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::WifiBle,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_dhcp.rs

@@ -20,7 +20,7 @@ use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::{print, println};
 use esp_wifi::{
     current_millis,
-    initialize,
+    init,
     wifi::{
         utils::create_network_interface,
         AccessPointInfo,
@@ -53,7 +53,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_access_point.rs

@@ -30,7 +30,7 @@ use esp_backtrace as _;
 use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::{print, println};
 use esp_wifi::{
-    initialize,
+    init,
     wifi::{
         AccessPointConfiguration,
         Configuration,
@@ -66,7 +66,7 @@ async fn main(spawner: Spawner) -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_access_point_with_sta.rs

@@ -33,7 +33,7 @@ use esp_backtrace as _;
 use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::{print, println};
 use esp_wifi::{
-    initialize,
+    init,
     wifi::{
         AccessPointConfiguration,
         ClientConfiguration,
@@ -74,7 +74,7 @@ async fn main(spawner: Spawner) -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_bench.rs

@@ -25,7 +25,7 @@ use esp_backtrace as _;
 use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::println;
 use esp_wifi::{
-    initialize,
+    init,
     wifi::{
         ClientConfiguration,
         Configuration,
@@ -97,7 +97,7 @@ async fn main(spawner: Spawner) -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_ble.rs

@@ -34,7 +34,7 @@ use esp_hal::{
     timer::timg::TimerGroup,
 };
 use esp_println::println;
-use esp_wifi::{ble::controller::asynch::BleConnector, initialize, EspWifiInitFor};
+use esp_wifi::{ble::controller::asynch::BleConnector, init, EspWifiInitFor};
 
 #[esp_hal_embassy::main]
 async fn main(_spawner: Spawner) -> ! {
@@ -49,7 +49,7 @@ async fn main(_spawner: Spawner) -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Ble,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_dhcp.rs

@@ -21,7 +21,7 @@ use esp_backtrace as _;
 use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::println;
 use esp_wifi::{
-    initialize,
+    init,
     wifi::{
         ClientConfiguration,
         Configuration,
@@ -60,7 +60,7 @@ async fn main(spawner: Spawner) -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_esp_now.rs

@@ -19,7 +19,7 @@ use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::println;
 use esp_wifi::{
     esp_now::{PeerInfo, BROADCAST_ADDRESS},
-    initialize,
+    init,
     EspWifiInitFor,
 };
 
@@ -36,7 +36,7 @@ async fn main(_spawner: Spawner) -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_esp_now_duplex.rs

@@ -19,7 +19,7 @@ use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::println;
 use esp_wifi::{
     esp_now::{EspNowManager, EspNowReceiver, EspNowSender, PeerInfo, BROADCAST_ADDRESS},
-    initialize,
+    init,
     EspWifiInitFor,
 };
 
@@ -46,7 +46,7 @@ async fn main(spawner: Spawner) -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_embassy_trouble.rs

@@ -44,7 +44,7 @@ async fn main(_s: Spawner) {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = esp_wifi::initialize(
+    let init = esp_wifi::init(
         esp_wifi::EspWifiInitFor::Ble,
         timg0.timer0,
         esp_hal::rng::Rng::new(peripherals.RNG),

examples/src/bin/wifi_esp_now.rs

@@ -15,7 +15,7 @@ use esp_println::println;
 use esp_wifi::{
     current_millis,
     esp_now::{PeerInfo, BROADCAST_ADDRESS},
-    initialize,
+    init,
     EspWifiInitFor,
 };
 
@@ -32,7 +32,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_sniffer.rs

@@ -24,7 +24,7 @@ use esp_hal::{
     timer::{timg::TimerGroup, AnyTimer, PeriodicTimer},
 };
 use esp_println::println;
-use esp_wifi::{initialize, wifi, EspWifiInitFor};
+use esp_wifi::{init, wifi, EspWifiInitFor};
 use ieee80211::{match_frames, mgmt_frame::BeaconFrame};
 
 static KNOWN_SSIDS: Mutex<RefCell<BTreeSet<String>>> = Mutex::new(RefCell::new(BTreeSet::new()));
@@ -44,7 +44,7 @@ fn main() -> ! {
     let timer0: AnyTimer = timg0.timer0.into();
     let timer = PeriodicTimer::new(timer0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timer,
         Rng::new(peripherals.RNG),

examples/src/bin/wifi_static_ip.rs

@@ -19,7 +19,7 @@ use esp_hal::{prelude::*, rng::Rng, timer::timg::TimerGroup};
 use esp_println::{print, println};
 use esp_wifi::{
     current_millis,
-    initialize,
+    init,
     wifi::{
         utils::create_network_interface,
         AccessPointInfo,
@@ -51,7 +51,7 @@ fn main() -> ! {
 
     let timg0 = TimerGroup::new(peripherals.TIMG0);
 
-    let init = initialize(
+    let init = init(
         EspWifiInitFor::Wifi,
         timg0.timer0,
         Rng::new(peripherals.RNG),

xtask/src/lib.rs

@@ -125,6 +125,19 @@ pub fn build_documentation(
         }
     }
 
+    if matches!(package, Package::EspWifi) {
+        features.push("utils".to_owned());
+        features.push("wifi".to_owned());
+        features.push("wifi-default".to_owned());
+        features.push("ble".to_owned());
+        features.push("coex".to_owned());
+        features.push("esp-now".to_owned());
+        features.push("sniffer".to_owned());
+        features.push("async".to_owned());
+        features.push("embassy-net".to_owned());
+        features.push("esp-hal/default".to_owned());
+    }
+
     // Build up an array of command-line arguments to pass to `cargo`:
     let builder = CargoArgsBuilder::default()
         .subcommand("doc")