diff --git a/.cargo/config.toml b/.cargo/config.toml index f1c155dc2..a00f10bd8 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/Cargo.toml b/Cargo.toml index 08ba8e29d..d2f93ad65 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/esp-alloc/Cargo.toml b/esp-alloc/Cargo.toml index 845d33bc4..29c9c8f33 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 b02d8def8..8d1f2d89f 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 5645465be..3a22ff78d 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 189197bed..c03b0fd5b 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 8a0ebb89b..bdbb43065 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 b1149e4cb..f76e24088 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 6962ef0b1..07a57086e 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 c54b3ce7c..b45ccae8d 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 93f16cebd..bd41b3e83 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 612b6bdb4..1be6cd63a 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 058d197a8..31e712289 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 a256e8f54..7adfda09e 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 fe3476aa1..dba60cdea 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 873b719c4..2cb34119b 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/xtask/Cargo.toml b/xtask/Cargo.toml index 840a7514c..a2b4fef66 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/documentation.rs b/xtask/src/documentation.rs index c1f61ce46..561ae2577 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 3a4c4e759..9689b3e06 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/xtask/src/main.rs b/xtask/src/main.rs index 05dacfdb5..cdf00c836 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<()> { diff --git a/xtensa-lx-rt-procmacros/Cargo.toml b/xtensa-lx-rt-proc-macros/Cargo.toml similarity index 84% rename from xtensa-lx-rt-procmacros/Cargo.toml rename to xtensa-lx-rt-proc-macros/Cargo.toml index 5c5132f3e..26e9f2fc4 100644 --- a/xtensa-lx-rt-procmacros/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-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 980dd5a47..29b63e717 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"] @@ -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" } diff --git a/xtensa-lx/Cargo.toml b/xtensa-lx/Cargo.toml index 561352c2e..b5201e212 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"]