From 69f76ea7223ac4bec2a58f69836f5b246fd07dbf Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Sun, 3 Mar 2024 18:11:13 -0700
Subject: [PATCH] ml-kem: add README.md

Uses the standard README.md template we use for all RustCrypto projects
---
 ml-kem/Cargo.toml |  5 ++++
 ml-kem/README.md  | 59 +++++++++++++++++++++++++++++++++++++++++++++++
 ml-kem/src/lib.rs | 20 +++++++++++-----
 3 files changed, 78 insertions(+), 6 deletions(-)
 create mode 100644 ml-kem/README.md

diff --git a/ml-kem/Cargo.toml b/ml-kem/Cargo.toml
index 438b150..f38ce79 100644
--- a/ml-kem/Cargo.toml
+++ b/ml-kem/Cargo.toml
@@ -4,6 +4,7 @@ version = "0.1.0"
 edition = "2021"
 rust-version = "1.74"
 license = "Apache-2.0 OR MIT"
+readme = "README.md"
 
 [features]
 default = ["std"]
@@ -24,3 +25,7 @@ rand = "0.8.5"
 [[bench]]
 name = "mlkem"
 harness = false
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]
diff --git a/ml-kem/README.md b/ml-kem/README.md
new file mode 100644
index 0000000..9836803
--- /dev/null
+++ b/ml-kem/README.md
@@ -0,0 +1,59 @@
+# [RustCrypto]: ML-KEM
+
+[![crate][crate-image]][crate-link]
+[![Docs][docs-image]][docs-link]
+[![Build Status][build-image]][build-link]
+![Apache2/MIT licensed][license-image]
+![Rust Version][rustc-image]
+[![Project Chat][chat-image]][chat-link]
+
+Pure Rust implementation of the Module-Lattice-Based Key-Encapsulation Mechanism Standard
+(formerly known as Kyber) as described in the [FIPS 203 Initial Public Draft].
+
+[Documentation][docs-link]
+
+## ⚠️ Security Warning
+
+The implementation contained in this crate has never been independently audited!
+
+USE AT YOUR OWN RISK!
+
+## Minimum Supported Rust Version
+
+This crate requires **Rust 1.74** at a minimum.
+
+We may change the MSRV in the future, but it will be accompanied by a minor
+version bump.
+
+## License
+
+Licensed under either of:
+
+- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+- [MIT license](http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
+
+[//]: # (badges)
+
+[crate-image]: https://buildstats.info/crate/ml-kem
+[crate-link]: https://crates.io/crates/ml-kem
+[docs-image]: https://docs.rs/ml-kem/badge.svg
+[docs-link]: https://docs.rs/ml-kem/
+[build-image]: https://github.com/RustCrypto/KEMs/actions/workflows/ml-kem.yml/badge.svg
+[build-link]: https://github.com/RustCrypto/KEMs/actions/workflows/ml-kem.yml
+[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
+[rustc-image]: https://img.shields.io/badge/rustc-1.74+-blue.svg
+[chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg
+[chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/406484-KEMs
+
+[//]: # (links)
+
+[RustCrypto]: https://github.com/rustcrypto
+[FIPS 203 Initial Public Draft]: https://csrc.nist.gov/pubs/fips/203/ipd
diff --git a/ml-kem/src/lib.rs b/ml-kem/src/lib.rs
index 3ac7766..52eeb29 100644
--- a/ml-kem/src/lib.rs
+++ b/ml-kem/src/lib.rs
@@ -1,3 +1,17 @@
+#![no_std]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+#![doc = include_str!("../README.md")]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg",
+    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg"
+)]
+#![warn(clippy::pedantic)] // Be pedantic by default
+#![allow(non_snake_case)] // Allow notation matching the spec
+#![allow(clippy::clone_on_copy)] // Be explicit about moving data
+#![deny(missing_docs)] // Require all public interfaces to be documented
+
+//! # Usage
+//!
 //! This crate implements the Module-Latice-based Key Encapsulation Method (ML-KEM) algorithm
 //! being standardized by NIST in FIPS 203.  ML-KEM is a KEM in the sense that it creates an
 //! (decapsulation key, encapsulation key) pair, such that anyone can use the encapsulation key to
@@ -23,12 +37,6 @@
 //!
 //! [RFC 9180]: https://www.rfc-editor.org/info/rfc9180
 
-#![no_std]
-#![warn(clippy::pedantic)] // Be pedantic by default
-#![allow(non_snake_case)] // Allow notation matching the spec
-#![allow(clippy::clone_on_copy)] // Be explicit about moving data
-#![deny(missing_docs)] // Require all public interfaces to be documented
-
 /// The inevitable utility module
 mod util;