improve documentation (#5)

* improve documentation

* fix missing anchors in documentation

* fmt

* clippy

* fix build workflow

* fix build workflow #2

---------

Co-authored-by: Konstantinos Athanasiou <[email protected]>

.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

Cargo.toml

@@ -1,6 +1,6 @@
 [workspace]
 members = ["protypo","protypo-cli"]
-exclude = ["examples/README.md","output"]
+exclude = ["output"]
 resolver = "2"
 
 [profile.release]

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`
+- [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).

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: [email protected]
+```
+
+
+## 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.

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:

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))