From a68475e79bab128bc87eae8df9002a7f2f84589d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Quentin?= Date: Thu, 6 Mar 2025 14:12:32 +0100 Subject: [PATCH 1/4] Support "build-documentation-index --serve" --- .cargo/config.toml | 2 +- xtask/Cargo.toml | 5 ++++- xtask/src/main.rs | 34 ++++++++++++++++++++++++++++++---- 3 files changed, 35 insertions(+), 6 deletions(-) diff --git a/.cargo/config.toml b/.cargo/config.toml index f1c155dc22..a00f10bd8d 100644 --- a/.cargo/config.toml +++ b/.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" diff --git a/xtask/Cargo.toml b/xtask/Cargo.toml index 840a7514ca..a2b4fef660 100644 --- a/xtask/Cargo.toml +++ b/xtask/Cargo.toml @@ -1,5 +1,5 @@ [package] -name = "xtask" +name = "xtask" version = "0.0.0" edition = "2021" publish = false @@ -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"] diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 05dacfdb5a..cdf00c8362 100644 --- a/xtask/src/main.rs +++ b/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, + #[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<()> { From 68da806a7ba77942d29bc025a2c8a319451793c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Quentin?= Date: Thu, 6 Mar 2025 17:28:17 +0100 Subject: [PATCH 2/4] Support `/latest` in generated docs --- Cargo.toml | 2 +- xtask/src/documentation.rs | 41 ++++++++++++++++++- xtask/src/lib.rs | 2 +- .../Cargo.toml | 0 .../src/lib.rs | 0 xtensa-lx-rt/Cargo.toml | 2 +- 6 files changed, 42 insertions(+), 5 deletions(-) rename {xtensa-lx-rt-procmacros => xtensa-lx-rt-proc-macros}/Cargo.toml (100%) rename {xtensa-lx-rt-procmacros => xtensa-lx-rt-proc-macros}/src/lib.rs (100%) diff --git a/Cargo.toml b/Cargo.toml index 08ba8e29d7..d2f93ad65e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -24,5 +24,5 @@ exclude = [ "qa-test", "xtensa-lx", "xtensa-lx-rt", - "xtensa-lx-rt-procmacros", + "xtensa-lx-rt-proc-macros", ] diff --git a/xtask/src/documentation.rs b/xtask/src/documentation.rs index c1f61ce467..0a6d6896eb 100644 --- a/xtask/src/documentation.rs +++ b/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!( + "", + 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 { 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() { diff --git a/xtask/src/lib.rs b/xtask/src/lib.rs index 3a4c4e759e..9689b3e06a 100644 --- a/xtask/src/lib.rs +++ b/xtask/src/lib.rs @@ -55,7 +55,7 @@ pub enum Package { QaTest, XtensaLx, XtensaLxRt, - XtensaLxRtProcmacros, + XtensaLxRtProcMacros, } impl Package { diff --git a/xtensa-lx-rt-procmacros/Cargo.toml b/xtensa-lx-rt-proc-macros/Cargo.toml similarity index 100% rename from xtensa-lx-rt-procmacros/Cargo.toml rename to xtensa-lx-rt-proc-macros/Cargo.toml diff --git a/xtensa-lx-rt-procmacros/src/lib.rs b/xtensa-lx-rt-proc-macros/src/lib.rs similarity index 100% rename from xtensa-lx-rt-procmacros/src/lib.rs rename to xtensa-lx-rt-proc-macros/src/lib.rs diff --git a/xtensa-lx-rt/Cargo.toml b/xtensa-lx-rt/Cargo.toml index 980dd5a476..b5f51c5a0d 100644 --- a/xtensa-lx-rt/Cargo.toml +++ b/xtensa-lx-rt/Cargo.toml @@ -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" } From d79348b2eadf8eab9b3a582f87e2244d3e3f447b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Quentin?= Date: Thu, 6 Mar 2025 17:57:06 +0100 Subject: [PATCH 3/4] `/latest` vs `/latest/` --- xtask/src/documentation.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xtask/src/documentation.rs b/xtask/src/documentation.rs index 0a6d6896eb..561ae25775 100644 --- a/xtask/src/documentation.rs +++ b/xtask/src/documentation.rs @@ -155,7 +155,7 @@ fn build_documentation_for_package( create_dir_all(latest_path.clone())?; std::fs::File::create(latest_path.clone().join("index.html"))?.write_all( format!( - "", + "", if package.chip_features_matter() { version.to_string() } else { From 45bc2bf50873e7ba086539e2265621c6cf6d838b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Quentin?= Date: Fri, 7 Mar 2025 10:10:07 +0100 Subject: [PATCH 4/4] Update documentation field --- esp-alloc/Cargo.toml | 2 +- esp-backtrace/Cargo.toml | 2 +- esp-build/Cargo.toml | 2 +- esp-config/Cargo.toml | 2 +- esp-hal-embassy/Cargo.toml | 2 +- esp-hal-procmacros/Cargo.toml | 2 +- esp-hal/Cargo.toml | 2 +- esp-ieee802154/Cargo.toml | 2 +- esp-lp-hal/Cargo.toml | 2 +- esp-metadata/Cargo.toml | 2 +- esp-println/Cargo.toml | 2 +- esp-riscv-rt/Cargo.toml | 2 +- esp-storage/Cargo.toml | 2 +- esp-wifi/Cargo.toml | 2 +- xtensa-lx-rt-proc-macros/Cargo.toml | 1 + xtensa-lx-rt/Cargo.toml | 2 +- xtensa-lx/Cargo.toml | 2 +- 17 files changed, 17 insertions(+), 16 deletions(-) diff --git a/esp-alloc/Cargo.toml b/esp-alloc/Cargo.toml index 845d33bc49..29c9c8f336 100644 --- a/esp-alloc/Cargo.toml +++ b/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" diff --git a/esp-backtrace/Cargo.toml b/esp-backtrace/Cargo.toml index b02d8def8a..8d1f2d89fb 100644 --- a/esp-backtrace/Cargo.toml +++ b/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" diff --git a/esp-build/Cargo.toml b/esp-build/Cargo.toml index 5645465beb..3a22ff78dd 100644 --- a/esp-build/Cargo.toml +++ b/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" diff --git a/esp-config/Cargo.toml b/esp-config/Cargo.toml index 189197bed2..c03b0fd5b7 100644 --- a/esp-config/Cargo.toml +++ b/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" diff --git a/esp-hal-embassy/Cargo.toml b/esp-hal-embassy/Cargo.toml index 8a0ebb89b9..bdbb430657 100644 --- a/esp-hal-embassy/Cargo.toml +++ b/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" diff --git a/esp-hal-procmacros/Cargo.toml b/esp-hal-procmacros/Cargo.toml index b1149e4cba..f76e24088f 100644 --- a/esp-hal-procmacros/Cargo.toml +++ b/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" diff --git a/esp-hal/Cargo.toml b/esp-hal/Cargo.toml index d2d753d925..d4c4f94187 100644 --- a/esp-hal/Cargo.toml +++ b/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" diff --git a/esp-ieee802154/Cargo.toml b/esp-ieee802154/Cargo.toml index c54b3ce7c9..b45ccae8da 100644 --- a/esp-ieee802154/Cargo.toml +++ b/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" diff --git a/esp-lp-hal/Cargo.toml b/esp-lp-hal/Cargo.toml index 93f16cebdd..bd41b3e83d 100644 --- a/esp-lp-hal/Cargo.toml +++ b/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" diff --git a/esp-metadata/Cargo.toml b/esp-metadata/Cargo.toml index 612b6bdb4e..1be6cd63a2 100644 --- a/esp-metadata/Cargo.toml +++ b/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" diff --git a/esp-println/Cargo.toml b/esp-println/Cargo.toml index 058d197a84..31e7122896 100644 --- a/esp-println/Cargo.toml +++ b/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" diff --git a/esp-riscv-rt/Cargo.toml b/esp-riscv-rt/Cargo.toml index a256e8f54c..7adfda09eb 100644 --- a/esp-riscv-rt/Cargo.toml +++ b/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" diff --git a/esp-storage/Cargo.toml b/esp-storage/Cargo.toml index fe3476aa1b..dba60cdea7 100644 --- a/esp-storage/Cargo.toml +++ b/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" diff --git a/esp-wifi/Cargo.toml b/esp-wifi/Cargo.toml index 873b719c4e..2cb34119b5 100644 --- a/esp-wifi/Cargo.toml +++ b/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" diff --git a/xtensa-lx-rt-proc-macros/Cargo.toml b/xtensa-lx-rt-proc-macros/Cargo.toml index 5c5132f3e9..26e9f2fc47 100644 --- a/xtensa-lx-rt-proc-macros/Cargo.toml +++ b/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"] diff --git a/xtensa-lx-rt/Cargo.toml b/xtensa-lx-rt/Cargo.toml index b5f51c5a0d..29b63e717d 100644 --- a/xtensa-lx-rt/Cargo.toml +++ b/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"] diff --git a/xtensa-lx/Cargo.toml b/xtensa-lx/Cargo.toml index 561352c2ed..b5201e2122 100644 --- a/xtensa-lx/Cargo.toml +++ b/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"]