From aaac8531de70a92b67361d6f61559fe4c43658e1 Mon Sep 17 00:00:00 2001 From: Predrag Gruevski <2348618+obi1kenobi@users.noreply.github.com> Date: Fri, 30 Jun 2023 12:27:25 -0400 Subject: [PATCH] Improve docs and README for `trustfall_stubgen`. (#334) --- Cargo.lock | 2 +- trustfall_stubgen/Cargo.toml | 2 +- trustfall_stubgen/README.md | 28 ++++++++++++++++++++++++++++ trustfall_stubgen/src/lib.rs | 28 ++++++++++++++++++++++++++-- 4 files changed, 56 insertions(+), 4 deletions(-) create mode 100644 trustfall_stubgen/README.md diff --git a/Cargo.lock b/Cargo.lock index a977be33..887d84bc 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3513,7 +3513,7 @@ dependencies = [ [[package]] name = "trustfall_stubgen" -version = "0.2.0" +version = "0.2.1" dependencies = [ "anyhow", "async-graphql-parser", diff --git a/trustfall_stubgen/Cargo.toml b/trustfall_stubgen/Cargo.toml index 6d0120c7..7879aeb5 100644 --- a/trustfall_stubgen/Cargo.toml +++ b/trustfall_stubgen/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "trustfall_stubgen" -version = "0.2.0" +version = "0.2.1" rust-version = "1.70" license = "Apache-2.0" description = "Generate a Trustfall adapter stub for a given schema." diff --git a/trustfall_stubgen/README.md b/trustfall_stubgen/README.md new file mode 100644 index 00000000..ce9cfe79 --- /dev/null +++ b/trustfall_stubgen/README.md @@ -0,0 +1,28 @@ +# trustfall_stubgen + +Given a Trustfall schema, autogenerate a high-quality Rust adapter stub +fully wired up with all types, properties, and edges referenced in the schema. + +First, install the CLI with: `cargo install --locked trustfall_stubgen --features cli` +Then generate Trustfall adapter stubs for your schema with: +``` +trustfall_stubgen --schema --target +``` +Under the hood this directly calls the [`generate_rust_stub`] function from this crate. +This crate can also be used as a library, so you can call that function directly from +your own code without going through the CLI. + +The generated Trustfall adapter stub has the following structure: +| file name | purpose | +| ---------------------- | ------------------------------------------------------ | +| adapter/mod.rs | connects everything together | +| adapter/schema.graphql | contains the schema for the adapter | +| adapter/adapter.rs | contains the adapter implementation | +| adapter/vertex.rs | contains the vertex type definition | +| adapter/entrypoints.rs | contains the entry points where all queries must start | +| adapter/properties.rs | contains the property implementations | +| adapter/edges.rs | contains the edge implementations | + +See an example of +[a generated adapter stub](https://github.com/obi1kenobi/trustfall/tree/main/trustfall_stubgen/test_data/expected_outputs/hackernews/adapter) +from this crate's test suite. diff --git a/trustfall_stubgen/src/lib.rs b/trustfall_stubgen/src/lib.rs index 58708d02..8d1b01eb 100644 --- a/trustfall_stubgen/src/lib.rs +++ b/trustfall_stubgen/src/lib.rs @@ -1,7 +1,31 @@ //! # trustfall_stubgen //! -//! Given a Trustfall schema, autogenerate a Rust adapter stub fully wired up with -//! all types, properties, and edges referenced in the schema. +//! Given a Trustfall schema, autogenerate a high-quality Rust adapter stub +//! fully wired up with all types, properties, and edges referenced in the schema. +//! +//! First, install the CLI with: `cargo install --locked trustfall_stubgen --features cli` +//! Then generate Trustfall adapter stubs for your schema with: +//! ``` +//! trustfall_stubgen --schema --target +//! ``` +//! Under the hood this directly calls the [`generate_rust_stub`] function from this crate. +//! This crate can also be used as a library, so you can call that function directly from +//! your own code without going through the CLI. +//! +//! The generated Trustfall adapter stub has the following structure: +//! | file name | purpose | +//! | ---------------------- | ------------------------------------------------------ | +//! | adapter/mod.rs | connects everything together | +//! | adapter/schema.graphql | contains the schema for the adapter | +//! | adapter/adapter.rs | contains the adapter implementation | +//! | adapter/vertex.rs | contains the vertex type definition | +//! | adapter/entrypoints.rs | contains the entry points where all queries must start | +//! | adapter/properties.rs | contains the property implementations | +//! | adapter/edges.rs | contains the edge implementations | +//! +//! See an example of +//! [a generated adapter stub](https://github.com/obi1kenobi/trustfall/tree/main/trustfall_stubgen/test_data/expected_outputs/hackernews/adapter) +//! from this crate's test suite. #![forbid(unsafe_code)]