From 54ce687a56326854090eb6ffcdcdb1ceb5cc12f1 Mon Sep 17 00:00:00 2001 From: Mike Rostecki Date: Tue, 1 Aug 2023 16:10:30 +0200 Subject: [PATCH] docs: Generate README with cargo-rdme --- .cargo-rdme.toml | 2 ++ .github/workflows/test.yml | 7 +++---- README.md | 34 ++++++++++++-------------------- README.tpl | 17 ---------------- xtask/src/generate_readme.rs | 38 ------------------------------------ xtask/src/main.rs | 4 ---- 6 files changed, 17 insertions(+), 85 deletions(-) create mode 100644 .cargo-rdme.toml delete mode 100644 README.tpl delete mode 100644 xtask/src/generate_readme.rs diff --git a/.cargo-rdme.toml b/.cargo-rdme.toml new file mode 100644 index 0000000..246bb1c --- /dev/null +++ b/.cargo-rdme.toml @@ -0,0 +1,2 @@ +workspace-project = "light-poseidon" +heading-base-level = 1 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index d0eabd6..37846d4 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -47,7 +47,6 @@ jobs: args: -- -D warnings - name: Check README - uses: actions-rs/cargo@v1 - with: - command: xtask - args: generate-readme --check + run: | + cargo install cargo-rdme + cargo rdme --check diff --git a/README.md b/README.md index 590b0dc..fdfb761 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ # light-poseidon + + **light-poseidon** is a [Poseidon](https://eprint.iacr.org/2019/458) hash implementation in Rust created for [Light Protocol](https://www.lightprotocol.com/). @@ -25,26 +27,23 @@ The parameters can be generated with: cargo xtask generate-poseidon-parameters ```` -# Output type +## Output type -[`Poseidon`](crate::Poseidon) type implements two traits which serve the purpose +[`Poseidon`](https://docs.rs/light-poseidon/latest/light_poseidon/struct.Poseidon.html) type implements two traits which serve the purpose of returning the calculated hash in different representations: -* [`PoseidonBytesHasher`](crate::PoseidonBytesHasher) with the - [`hash_bytes_be`](crate::PoseidonBytesHasher::hash_bytes_be) and - [`hash_bytes_le`](crate::PoseidonBytesHasher::hash_bytes_le) methods which - returns a byte array. -* [`PoseidonHasher`](crate::PoseidonHasher) with the - [`hash`](crate::PoseidonHasher::hash) method which returns +* [`PoseidonBytesHasher`](https://docs.rs/light-poseidon/latest/light_poseidon/trait.PoseidonBytesHasher.html) with the + `hash_bytes_be` and `hash_bytes_le` methods which returns a byte array. +* [`PoseidonHasher`](https://docs.rs/light-poseidon/latest/light_poseidon/trait.PoseidonHasher.html) with the `hash` method which returns [`ark_ff::PrimeField`](ark_ff::PrimeField). Might be useful if you want to immediately process the result with an another library which works with [`ark_ff::PrimeField`](ark_ff::PrimeField) types. -# Examples +## Examples Example with two simple big-endian byte inputs (converted to field elements) and BN254-based parameters provided by the library, with -[`PoseidonBytesHasher`](crate::PoseidonHasher) trait and a byte array +[`PoseidonBytesHasher`](https://docs.rs/light-poseidon/latest/light_poseidon/trait.PoseidonHasher.html) trait and a byte array result: ```rust @@ -64,7 +63,7 @@ println!("{:?}", hash); // ] ``` -With [`PoseidonHasher`][crate::PoseidonHasher] trait and +With [`PoseidonHasher`](https://docs.rs/light-poseidon/latest/light_poseidon/trait.PoseidonHasher.html) trait and [`ark_ff::PrimeField`](ark_ff::PrimeField) result: ```rust @@ -91,7 +90,7 @@ but it was also inspired by the following ones: * [circomlibjs](https://github.com/iden3/circomlibjs) * [zero-knowledge-gadgets](https://github.com/webb-tools/zero-knowledge-gadgets) -### Performance +## Performance This repository contains a benchmark measuring the performance of this Poseidon implementation for given 1 - 12 random 32 bytes inputs. @@ -141,13 +140,4 @@ poseidon_bn254_x5_12 time: [295.47 µs 305.80 µs 316.41 µs] This library has been audited by [Veridise](https://veridise.com/). You can read the audit report [here](https://github.com/Lightprotocol/light-poseidon/blob/main/assets/audit.pdf). -## License - -Licensed under [Apache License, Version 2.0](LICENSE). - -### 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. \ No newline at end of file + diff --git a/README.tpl b/README.tpl deleted file mode 100644 index 858f957..0000000 --- a/README.tpl +++ /dev/null @@ -1,17 +0,0 @@ -[![Crates.io](https://img.shields.io/crates/v/light-poseidon.svg)](https://crates.io/crates/light-poseidon) -[![Workflow Status](https://github.com/Lightprotocol/light-poseidon/workflows/main/badge.svg)](https://github.com/Lightprotocol/light-poseidon/actions?query=workflow) - -# {{crate}} - -{{readme}} - -## License - -Licensed under [Apache License, Version 2.0](LICENSE). - -### 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. diff --git a/xtask/src/generate_readme.rs b/xtask/src/generate_readme.rs deleted file mode 100644 index b18d936..0000000 --- a/xtask/src/generate_readme.rs +++ /dev/null @@ -1,38 +0,0 @@ -use std::{env::current_dir, fs::File}; - -use clap::Parser; - -#[derive(Debug, Parser)] -pub struct Options { - /// Do not overwrite the README.md file, just check whether it is up to date. - #[clap(long, default_value_t = false)] - check: bool, -} - -pub fn generate_readme(opts: Options) -> anyhow::Result<()> { - let project_root = current_dir()?.join("light-poseidon"); - let mut source = File::open("light-poseidon/src/lib.rs")?; - let mut template = File::open("README.tpl")?; - - let content = cargo_readme::generate_readme( - project_root.as_path(), - &mut source, - Some(&mut template), - true, - true, - true, - true, - ) - .map_err(|e| anyhow::anyhow!(e))?; - - if opts.check { - let readme = std::fs::read_to_string("README.md")?; - if readme != content { - anyhow::bail!("README.md is not up to date"); - } - } else { - std::fs::write("README.md", content)?; - } - - Ok(()) -} diff --git a/xtask/src/main.rs b/xtask/src/main.rs index 1ec74a2..4b07111 100644 --- a/xtask/src/main.rs +++ b/xtask/src/main.rs @@ -1,7 +1,6 @@ use clap::Parser; mod generate_parameters; -mod generate_readme; #[derive(Parser)] pub struct XtaskOptions { @@ -12,8 +11,6 @@ pub struct XtaskOptions { #[derive(Parser)] enum Command { GeneratePoseidonParameters(generate_parameters::Options), - /// Generate the README.md file. - GenerateReadme(generate_readme::Options), } fn main() -> Result<(), anyhow::Error> { @@ -23,7 +20,6 @@ fn main() -> Result<(), anyhow::Error> { Command::GeneratePoseidonParameters(opts) => { generate_parameters::generate_parameters(opts)? } - Command::GenerateReadme(opts) => generate_readme::generate_readme(opts)?, } Ok(())