From b6f8a7fc6046b7946b62579e772a60c159bab554 Mon Sep 17 00:00:00 2001 From: Konstantinos Athanasiou Date: Thu, 9 Jan 2025 19:24:57 +0200 Subject: [PATCH] improve documentation (#5) * improve documentation * fix missing anchors in documentation * fmt * clippy * fix build workflow * fix build workflow #2 --------- Co-authored-by: Konstantinos Athanasiou --- .github/workflows/build.yml | 6 ++- Cargo.toml | 2 +- README.md | 70 ++++++++++++++++++++++++++--- generators/README.md | 70 +++++++++++++++++++++++++++++ generators/spring-rs/Generator.yaml | 7 --- protypo/src/lib.rs | 12 +++-- 6 files changed, 147 insertions(+), 20 deletions(-) create mode 100644 generators/README.md diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6552acf..370f4d8 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -2,8 +2,10 @@ name: Build on: push: paths: - - 'src/**' - - 'Cargo.toml' + - 'protypo/src/**' + - 'protypo/Cargo.toml' + - 'protypo-cli/src/**' + - 'protypo-cli/Cargo.toml' env: RUST_TOOLCHAIN: stable diff --git a/Cargo.toml b/Cargo.toml index 6d5a9ba..b233a0d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] members = ["protypo","protypo-cli"] -exclude = ["examples/README.md","output"] +exclude = ["output"] resolver = "2" [profile.release] diff --git a/README.md b/README.md index 44a7efc..abef206 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,65 @@ -# protypo -A rust based template based code generator inspired by helm, jhipster and openapi-generator +# Protypo -# Installation -Install with cargo install `cargo install --git https://github.com/dinosath/protypo.git` +## πŸ“– Table of Contents -# generate -- `protypo generate -p path/to/generator/` -- `protypo generate -p generators/loco-react-admin` \ No newline at end of file +- [Introduction](#-introduction) +- [Features](#features) +- [Installation](#-installation) +- [Usage](#-usage) +- [Generators](#-generators) +- [Contributing](#-contributing) +- [License](#-license) + +## πŸ“ Introduction + +Protypo simplifies the process of generating backend code using JSON schemas, allowing you to focus on business logic and reducing repetitive tasks. It can generate code for various languages using customizable templates, making it a versatile tool for API generation, code scaffolding, and more. + +Protypo was built to bring the speed and flexibility of low-code tools to Rust, with the extensibility and performance expected from a modern Rust-based tool. + +## Features +- πŸš€ Supports `Tera` (default) and `MiniJinja` template engines. +- πŸ› οΈ Generates code based on JSON schemas for APIs, microservices, and more. +- πŸ“¦ Customizable generators for different frameworks and programming languages. +- πŸ“‚ Project structure designed for flexibility and scalability. +- πŸ”§ Extensible configuration files for defining templates, dependencies, and resources. + +## βš™οΈ Installation + +To install Protypo, follow the steps below: + +### Using Cargo + +1. Ensure you have [Rust](https://www.rust-lang.org/tools/install) installed. +2. Install Protypo via Cargo: + + ```bash + cargo install --git https://github.com/dinosath + ``` + +#### πŸš€ Usage + +Protypo can be used from the command line. Run the following to generate code: + +```bash + protypo generate -p path/to/generator +``` + +### πŸ“ Generators + +For more info about the generators and how to create a new generator extend an existing one. [documentation](./generators/README.md) + +### 🀝 Contributing + +Contributions are welcome! If you’d like to contribute to Protypo, feel free to open issues, submit pull requests, or suggest new features. +How to Contribute + +1. Fork the repository. +2. Create a new branch. +3. Make your changes. +4. Submit a pull request. + +Please ensure your contributions follow the Rust community’s best practices. + +### πŸ“„ License + +Protypo is licensed under the MIT License. See the LICENSE [here](./LICENSE). \ No newline at end of file diff --git a/generators/README.md b/generators/README.md new file mode 100644 index 0000000..c78b4df --- /dev/null +++ b/generators/README.md @@ -0,0 +1,70 @@ +# Generators Documentation + +## Overview + +This documentation provides an overview of the generators available in the Protypo project and guides on how to extend them. + +A generator in Protypo is a collection of templates, configuration files, and resources that define the code generation structure. + +### Structure + +A generator typically follows this structure: + +``` +/generator +β”œβ”€β”€ Generator.yaml +β”œβ”€β”€ files/ +β”œβ”€β”€ templates/ +β”œβ”€β”€ values.yaml +└── entities/ +``` + +* `Generator.yaml`: Contains the metadata for the generator, such as version, description, dependencies, and maintainers. +* `files/`: Contains files that are copied directly to the output directory. +* `templates/`: Holds template files that are used to generate code. +* `values.yaml`: Defines default values used within the templates, which can be overridden by command-line arguments or schema files. +* `entities/`: Stores the JSON schema files that describe the entities used in the templates. + +#### Sample Generator + +Here’s an example of a generator configuration for Rust projects using the spring-rs framework: + +```yaml +apiVersion: v1 +name: jsonschema-commons +version: 0.0.1 +description: Package containing common macros for handling jsonschema files. Use in tera templates. +keywords: + - jsonschema-commons + - jsonschema + - commons + - tera +sources: + - https://github.com/dinosath/protypo +maintainers: + - name: Konstantinos Athanasiou + email: dinosath0@gmail.com +``` + + +## Available Generators + +* `jdl` +* `jsonschema-commons` +* `loco` +* `loco-react-admin` +* `react-admin` +* `seaography` +* `seaorm-entities` +* `shuttle` +* `spring-rs` +* `spring-rs-react-admin` + +## Generation + +During generation the values are all merged in one object from the deepest to the oldest in the hierarchy. + +The templates will be used to generate code based on the provided values and entities. + +### Loading Order +Generators are loaded from the deepest to the highest in the directory tree. If there is a template with the same name in a higher order directory, it will override the one in the lower order directory. In the context of the templates, the entities will be loaded in the same depth-first approach and will be merged with the oldest. \ No newline at end of file diff --git a/generators/spring-rs/Generator.yaml b/generators/spring-rs/Generator.yaml index 49bb3bb..7ed08ac 100644 --- a/generators/spring-rs/Generator.yaml +++ b/generators/spring-rs/Generator.yaml @@ -14,13 +14,6 @@ dependencies: tags: - seaorm - rust - - name: seaography - version: 0.0.1 - url: "file://../seaography" - tags: - - seaography - - seaorm - - rust sources: - https://github.com/dinosath/protypo maintainers: diff --git a/protypo/src/lib.rs b/protypo/src/lib.rs index 5644b84..e1db08f 100644 --- a/protypo/src/lib.rs +++ b/protypo/src/lib.rs @@ -1,6 +1,6 @@ use glob::glob; use json_value_merge::Merge; -use rrgen::{Error, RRgen}; +use rrgen::RRgen; use serde::{Deserialize, Serialize}; use serde_json::{json, Map, Value}; use std::collections::HashMap; @@ -246,9 +246,15 @@ impl Generator { context.insert("entities".to_string(), self.collect_entities()); let binding = collect_templates(self); - let templates: Vec<_> = binding.iter().map(|(s1, s2)| (s1.as_str(), s2.as_str())).collect(); + let templates: Vec<_> = binding + .iter() + .map(|(s1, s2)| (s1.as_str(), s2.as_str())) + .collect(); let rrgen = RRgen::with_templates(templates).map_err(|err| { - std::io::Error::new(std::io::ErrorKind::Other, format!("Could not initialize rrgen, due to error: {:?}", err)) + std::io::Error::new( + std::io::ErrorKind::Other, + format!("Could not initialize rrgen, due to error: {:?}", err), + ) })?; self.generate_templates(&rrgen, &Value::Object(context))