From 74bd46091916533e9fbc2b833e39fdfdec49d5e5 Mon Sep 17 00:00:00 2001 From: Giovanni Colapinto Date: Tue, 15 Oct 2024 13:39:57 +0000 Subject: [PATCH 1/2] Add content to lib.rs to be displayed as main page on docs.rs Signed-off-by: Giovanni Colapinto --- src/lib.rs | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index ee95e44..ce88710 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -4,5 +4,82 @@ // license that can be found in the LICENSE file or at // https://opensource.org/licenses/MIT. +//! The **OCP Test & Validation Initiative** is a collaboration between datacenter hyperscalers having the goal of standardizing aspects of the hardware validation/diagnosis space, along with providing necessary tooling to enable both diagnostic developers and executors to leverage these interfaces. +//! +//! Specifically, the [ocp-diag-core-rust](https://github.com/opencomputeproject/ocp-diag-core-rust) project makes it easy for developers to use the **OCP Test & Validation specification** artifacts by presenting a pure-rust api that can be used to output spec compliant JSON messages. +//! +//! To start, please see below for [installation instructions](https://github.com/opencomputeproject/ocp-diag-core-rust#installation) and [usage](https://github.com/opencomputeproject/ocp-diag-core-rust#usage). +//! +//! This project is part of [ocp-diag-core](https://github.com/opencomputeproject/ocp-diag-core) and exists under the same [MIT License Agreement](https://github.com/opencomputeproject/ocp-diag-core-rust/LICENSE). +//! +//! ### Usage +//! +//! The [specification](https://github.com/opencomputeproject/ocp-diag-core/tree/main/json_spec) does not impose any particular level of usage. To be compliant, a diagnostic package just needs output the correct artifact messages in the correct format. However, any particular such diagnostic is free to choose what aspects it needs to use/output; eg. a simple validation test may not output any measurements, opting to just have a final Diagnosis outcome. +//! +//! A very simple starter example, which just outputs a diagnosis: +//! ```rust +//! use anyhow::Result; +//! +//! use ocptv::output as tv; +//! use ocptv::{ocptv_diagnosis_fail, ocptv_diagnosis_pass}; +//! use rand::Rng; +//! use tv::{TestResult, TestStatus}; +//! +//! fn get_fan_speed() -> i32 { +//! let mut rng = rand::thread_rng(); +//! rng.gen_range(1500..1700) +//! } +//! +//! async fn run_diagnosis_step(step: tv::ScopedTestStep) -> Result { +//! let fan_speed = get_fan_speed(); +//! +//! if fan_speed >= 1600 { +//! step.add_diagnosis("fan_ok", tv::DiagnosisType::Pass).await?; +//! } else { +//! step.add_diagnosis("fan_low", tv::DiagnosisType::Fail).await?; +//! } +//! +//! Ok(TestStatus::Complete) +//! } +//! +//! async fn run_diagnosis_macros_step(step: tv::ScopedTestStep) -> Result { +//! let fan_speed = get_fan_speed(); +//! +//! /// using the macro, the source location is filled automatically +//! if fan_speed >= 1600 { +//! ocptv_diagnosis_pass!(step, "fan_ok").await?; +//! } else { +//! ocptv_diagnosis_fail!(step, "fan_low").await?; +//! } +//! +//! Ok(TestStatus::Complete) +//! } +//! +//! #[tokio::main] +//! async fn main() -> Result<()> { +//! let dut = tv::DutInfo::builder("dut0").build(); +//! +//! tv::TestRun::builder("simple measurement", "1.0") +//! .build() +//! .scope(dut, |r| async move { +//! r.add_step("step0") +//! .scope(run_diagnosis_step) +//! .await?; +//! +//! r.add_step("step1") +//! .scope(run_diagnosis_macros_step) +//! .await?; +//! +//! Ok(tv::TestRunOutcome { +//! status: TestStatus::Complete, +//! result: TestResult::Pass, +//! }) +//! }) +//! .await?; +//! +//! Ok(()) +//! } +//! ``` + pub mod output; mod spec; From 081cd2d46d7a0a65feef28c9f79e5a357b5a8513 Mon Sep 17 00:00:00 2001 From: Giovanni Colapinto Date: Fri, 8 Nov 2024 15:50:33 +0000 Subject: [PATCH 2/2] Add documentation to be displayed on https://docs.rs/ocptv/ Signed-off-by: Giovanni Colapinto --- Cargo.lock | 2 +- Cargo.toml | 2 +- DEVELOPERS.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b8bae04..bbc9816 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -685,7 +685,7 @@ dependencies = [ [[package]] name = "ocptv" -version = "0.1.3" +version = "0.1.4" dependencies = [ "anyhow", "assert-json-diff", diff --git a/Cargo.toml b/Cargo.toml index 62c8632..2db6ccf 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "ocptv" -version = "0.1.3" +version = "0.1.4" description = "Strongly typed Rust API for OCPTV output" authors = ["OCP Test & Validation Project"] keywords = ["ocptv", "hardware", "validation"] diff --git a/DEVELOPERS.md b/DEVELOPERS.md index ed9409d..aab0722 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -18,8 +18,8 @@ Steps: 1. bump the version. Will need [`cargo-release`](https://crates.io/crates/cargo-release) crate. Example here bumps the *patch* version (see [cargo semver](https://doc.rust-lang.org/cargo/reference/semver.html) when deciding which version number to bump). ```bash $ git checkout dev -$ cargo release version patch --execute # also note to update the readme $ cargo release changes # note any changelog to add to the commit, or manually craft it +$ cargo release version patch --execute # also note to update the readme $ git add . $ git commit $ git push origin dev