Xtask/latest redirect (#3231)

* Support "build-documentation-index --serve"

* Support `/latest` in generated docs

* `/latest` vs `/latest/`

* Update documentation field

.cargo/config.toml

@@ -1,5 +1,5 @@
 [alias]
 xtask = "run --package xtask --"
-xdoc = "run --package xtask --features=deploy-docs --"
+xdoc = "run --package xtask --features=deploy-docs,preview-docs --"
 xfmt = "xtask fmt-packages"
 qa = "xtask run-example qa-test"

Cargo.toml

@@ -24,5 +24,5 @@ exclude  = [
     "qa-test",
     "xtensa-lx",
     "xtensa-lx-rt",
-    "xtensa-lx-rt-procmacros",
+    "xtensa-lx-rt-proc-macros",
 ]

esp-alloc/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.7.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "A heap allocator for Espressif devices"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-alloc/latest/"
 keywords      = ["allocator", "embedded", "esp32", "espressif", "memory"]
 categories    = ["embedded", "memory-management", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-backtrace/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.15.1"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Bare-metal backtrace support for Espressif devices"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-backtrace/latest/"
 keywords      = ["backtrace", "embedded", "esp32", "espressif"]
 categories    = ["embedded", "hardware-support", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-build/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.2.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Build utilities for esp-hal"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-build/latest/"
 repository    = "https://github.com/esp-rs/esp-hal"
 license       = "MIT OR Apache-2.0"
 

esp-config/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.3.1"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Configure projects using esp-hal and related packages"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-config/latest/"
 repository    = "https://github.com/esp-rs/esp-hal"
 license       = "MIT OR Apache-2.0"
 

esp-hal-embassy/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.7.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Embassy support for esp-hal"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-hal-embassy/latest/"
 keywords      = ["async", "embedded", "esp32", "espressif"]
 categories    = ["asynchronous", "embedded", "hardware-support", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-hal-procmacros/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.17.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Procedural macros for esp-hal"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-hal-procmacros/latest/"
 repository    = "https://github.com/esp-rs/esp-hal"
 license       = "MIT OR Apache-2.0"
 

esp-hal/Cargo.toml

@@ -4,7 +4,7 @@ version       = "1.0.0-beta.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Bare-metal HAL for Espressif devices"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-hal/latest/"
 keywords      = ["embedded", "embedded-hal", "esp32", "espressif", "hal"]
 categories    = ["embedded", "hardware-support", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-ieee802154/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.6.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Low-level IEEE 802.15.4 driver for the ESP32-C6 and ESP32-H2"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-ieee802154/latest/"
 keywords      = ["embedded", "esp32", "espressif", "ieee802154", "wpan"]
 categories    = ["embedded", "network-programming", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-lp-hal/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.1.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "HAL for low-power RISC-V coprocessors found in ESP32 devices"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-lp-hal/latest/"
 keywords      = ["embedded", "embedded-hal", "esp32", "espressif", "hal"]
 categories    = ["embedded", "hardware-support", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-metadata/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.6.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Metadata for Espressif devices"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-metadata/latest/"
 repository    = "https://github.com/esp-rs/esp-hal"
 license       = "MIT OR Apache-2.0"
 

esp-println/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.13.1"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Provides `print!` and `println!` implementations various Espressif devices"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-println/latest/"
 keywords      = ["defmt", "embedded", "esp32", "espressif", "logging"]
 categories    = ["embedded", "hardware-support", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-riscv-rt/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.10.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Minimal runtime / startup for RISC-V CPUs from Espressif"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-riscv-rt/latest/"
 keywords      = ["esp32", "espressif", "riscv", "runtime", "startup"]
 categories    = ["embedded", "hardware-support", "no-std"]
 repository    = "https://github.com/esp-rs/esp-hal"

esp-storage/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.5.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Implementation of embedded-storage traits to access unencrypted ESP32 flash"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-storage/latest/"
 keywords      = ["embedded-storage", "esp32", "espressif", "no-std"]
 categories    = ["embedded", "hardware-support", "no-std"]
 repository    = "https://github.com/esp-rs/esp-storage"

esp-wifi/Cargo.toml

@@ -4,7 +4,7 @@ version = "0.13.0"
 edition = "2021"
 rust-version  = "1.84.0"
 description = "A WiFi, Bluetooth and ESP-NOW driver for use with Espressif chips and bare-metal Rust"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/esp-wifi/latest/"
 keywords = ["wifi", "bluetooth", "esp-now", "esp32", "no-std"]
 categories = ["embedded", "hardware-support", "no-std"]
 repository = "https://github.com/esp-rs/esp-hal"

xtask/Cargo.toml

@@ -16,6 +16,8 @@ esp-metadata = { path = "../esp-metadata", features = ["clap"] }
 kuchikiki    = "0.8.2"
 log          = "0.4.22"
 minijinja    = "2.5.0"
+opener       = { version = "0.7.2", optional = true }
+rocket       = { version = "0.5.1", optional = true }
 semver       = { version = "1.0.23", features = ["serde"] }
 serde        = { version = "1.0.215", features = ["derive"] }
 serde_json   = "1.0.70"
@@ -32,3 +34,4 @@ reqwest = { version = "0.12.12", features = [
 
 [features]
 deploy-docs = ["dep:reqwest"]
+preview-docs = ["dep:rocket", "dep:opener"]

xtask/src/documentation.rs

@@ -1,6 +1,7 @@
 use std::{
     collections::HashSet,
-    fs,
+    fs::{self, create_dir_all},
+    io::Write,
     path::{Path, PathBuf},
 };
 
@@ -139,6 +140,35 @@ fn build_documentation_for_package(
         )
     })?;
 
+    // create "/latest" redirect - assuming that the current version is the latest
+    let latest_path = if package.chip_features_matter() {
+        output_path
+            .parent()
+            .unwrap()
+            .parent()
+            .unwrap()
+            .join("latest")
+    } else {
+        output_path.parent().unwrap().join("latest")
+    };
+    log::info!("Creating latest version redirect at {:?}", latest_path);
+    create_dir_all(latest_path.clone())?;
+    std::fs::File::create(latest_path.clone().join("index.html"))?.write_all(
+        format!(
+            "<meta http-equiv=\"refresh\" content=\"0; url=../{}/\" />",
+            if package.chip_features_matter() {
+                version.to_string()
+            } else {
+                format!(
+                    "{}/{}",
+                    version.to_string(),
+                    package.to_string().replace('-', "_")
+                )
+            }
+        )
+        .as_bytes(),
+    )?;
+
     Ok(())
 }
 
@@ -255,6 +285,9 @@ fn apply_feature_rules(package: &Package, config: &Config) -> Vec<String> {
         Package::EspHalEmbassy => {
             features.push("esp-hal/unstable".to_owned());
         }
+        Package::EspIeee802154 => {
+            features.push("esp-hal/unstable".to_owned());
+        }
         _ => {}
     }
 
@@ -337,7 +370,7 @@ pub fn build_documentation_index(workspace: &Path, packages: &mut [Package]) ->
         let mut device_doc_paths = Vec::new();
 
         // Each path we iterate over should be the directory for a given version of
-        // the package's documentation:
+        // the package's documentation: (except latest)
         for version_path in fs::read_dir(package_docs_path)? {
             let version_path = version_path?.path();
             if version_path.is_file() {
@@ -348,6 +381,10 @@ pub fn build_documentation_index(workspace: &Path, packages: &mut [Package]) ->
                 continue;
             }
 
+            if version_path.file_name().unwrap() == "latest" {
+                continue;
+            }
+
             for path in fs::read_dir(&version_path)? {
                 let path = path?.path();
                 if path.is_dir() {

xtask/src/lib.rs

@@ -55,7 +55,7 @@ pub enum Package {
     QaTest,
     XtensaLx,
     XtensaLxRt,
-    XtensaLxRtProcmacros,
+    XtensaLxRtProcMacros,
 }
 
 impl Package {

xtask/src/main.rs

@@ -12,9 +12,7 @@ use strum::IntoEnumIterator;
 use xtask::{
     cargo::{CargoAction, CargoArgsBuilder},
     firmware::Metadata,
-    target_triple,
-    Package,
-    Version,
+    target_triple, Package, Version,
 };
 
 // ----------------------------------------------------------------------------
@@ -104,6 +102,9 @@ struct BuildDocumentationIndexArgs {
     /// Package(s) to build documentation index for.
     #[arg(long, value_enum, value_delimiter = ',', default_values_t = Package::iter())]
     packages: Vec<Package>,
+    #[cfg(feature = "preview-docs")]
+    #[arg(long)]
+    serve: bool,
 }
 
 #[derive(Debug, Args)]
@@ -514,7 +515,32 @@ fn build_documentation_index(
     workspace: &Path,
     mut args: BuildDocumentationIndexArgs,
 ) -> Result<()> {
-    xtask::documentation::build_documentation_index(workspace, &mut args.packages)
+    xtask::documentation::build_documentation_index(workspace, &mut args.packages)?;
+
+    #[cfg(feature = "preview-docs")]
+    if args.serve {
+        std::thread::spawn(|| {
+            std::thread::sleep(std::time::Duration::from_millis(1000));
+            opener::open_browser("http://127.0.0.1:8000/").ok();
+        });
+
+        rocket::async_main(
+            {
+                rocket::build().mount(
+                    "/",
+                    rocket::fs::FileServer::new(
+                        "docs",
+                        rocket::fs::Options::Index
+                            | rocket::fs::Options::IndexFile
+                            | rocket::fs::Options::DotFiles,
+                    ),
+                )
+            }
+            .launch(),
+        )?;
+    }
+
+    Ok(())
 }
 
 fn build_package(workspace: &Path, args: BuildPackageArgs) -> Result<()> {

xtensa-lx-rt-proc-macros/Cargo.toml

@@ -4,6 +4,7 @@ version = "0.2.2"
 edition = "2021"
 rust-version = "1.84.0"
 description = "Attributes re-exported in `xtensa-lx-rt`"
+documentation = "https://docs.espressif.com/projects/rust/xtensa-lx-rt-proc-macros/latest/"
 repository = "https://github.com/esp-rs/esp-hal"
 license = "MIT OR Apache-2.0"
 keywords = ["esp32", "xtensa-lx-rt", "runtime", "startup"]

xtensa-lx-rt/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.18.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Minimal startup/runtime for Xtensa LX CPUs"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/xtensa-lx-rt/latest/"
 repository    = "https://github.com/esp-rs/esp-hal"
 license       = "MIT OR Apache-2.0"
 keywords      = ["lx", "peripheral", "register", "xtensa"]
@@ -15,7 +15,7 @@ features = ["esp32"]
 
 [dependencies]
 document-features = "0.2.10"
-macros            = { version = "0.2.2", package = "xtensa-lx-rt-proc-macros", path = "../xtensa-lx-rt-procmacros" }
+macros            = { version = "0.2.2", package = "xtensa-lx-rt-proc-macros", path = "../xtensa-lx-rt-proc-macros" }
 r0                = "1.0.0"
 xtensa-lx         = { version = "0.10.0", path = "../xtensa-lx" }
 

xtensa-lx/Cargo.toml

@@ -4,7 +4,7 @@ version       = "0.10.0"
 edition       = "2021"
 rust-version  = "1.84.0"
 description   = "Low-level access to Xtensa LX processors and peripherals"
-documentation = "https://docs.espressif.com/projects/rust/"
+documentation = "https://docs.espressif.com/projects/rust/xtensa-lx/latest/"
 repository    = "https://github.com/esp-rs/esp-hal"
 license       = "MIT OR Apache-2.0"
 categories    = ["embedded", "hardware-support", "no-std"]