5 generate rustdoc (#40)

* fixed compiled code not to be runnable

* added rust documentation generation to main function

* added cargo doc command and a basic readme to the template

* try to make clippy understand

* fix clippy

---------

Co-authored-by: Stanislav Kosorin <stanislav.kosorin@cresta.ai>

Author: doepnern

example/specs/basic.yaml

@@ -2,6 +2,7 @@ asyncapi: 2.1.0
 info:
   title: My_API
   version: 1.0.0
+  description: a basic test api
 servers:
   production:
     url: demo.nats.io

src/generator/common.rs

@@ -44,3 +44,12 @@ pub fn template_render_write<T: Into<gtmpl::Value>>(
     let render = gtmpl::template(&template, context_ref).expect("Could not inject template");
     utils::write_to_path_create_dir(&render, output_path).unwrap();
 }
+
+pub fn cargo_generate_rustdoc(path: &Path) {
+    Command::new("cargo")
+        .current_dir(path)
+        .arg("doc")
+        .arg("--no-deps")
+        .output()
+        .expect("failed to generate rustdoc");
+}

src/generator/mod.rs

@@ -1,5 +1,6 @@
 mod common;
 pub use common::cargo_add;
 pub use common::cargo_fmt;
+pub use common::cargo_generate_rustdoc;
 pub use common::cargo_init_project;
 pub use common::template_render_write;

src/main.rs

@@ -5,7 +5,7 @@ mod parser;
 mod template_model;
 mod utils;
 
-use crate::generator::template_render_write;
+use crate::generator::{cargo_generate_rustdoc, template_render_write};
 use clap::Parser;
 use generator::{cargo_add, cargo_fmt, cargo_init_project};
 use std::path::Path;
@@ -22,16 +22,16 @@ fn main() {
     let spec = parser::parse_spec_to_model(specfile_path, validator_schema_path).unwrap();
     println!("{:?}", spec);
 
-    let title = match args.project_title {
+    let title: &str = match &args.project_title {
         Some(t) => t,
-        None => spec.info.title.clone(),
+        None => &spec.info.title,
     };
-    // output_path
     let output = args.output_directory;
     let output_path = &Path::new(&output).join(title.replace(' ', "_").to_lowercase());
     println!("output_path: {:?}", output_path);
 
     let async_config = parser::spec_to_pubsub_template_type(&spec).unwrap();
+
     // render template and write
     template_render_write(
         &template_path.join("main.rs"),
@@ -43,11 +43,21 @@ fn main() {
         &async_config,
         &output_path.join("src/handler.rs"),
     );
+    template_render_write(
+        &template_path.join("Readme.md"),
+        &async_config,
+        &output_path.join("Readme.md"),
+    );
     // make output a compilable project
     cargo_init_project(output_path);
     cargo_fmt(&output_path.join("src/main.rs"));
     cargo_add(output_path, "tokio", Some("rt-multi-thread")); // when there are more crates move to generator.rs
     cargo_add(output_path, "async_nats", None);
     cargo_add(output_path, "futures", None);
     cargo_add(output_path, "serde", None);
+    println!("generating docs...");
+    println!(
+        "this may take a while, you can already use the generated project in the output directory"
+    );
+    cargo_generate_rustdoc(output_path);
 }

src/parser/pubsub.rs

@@ -108,6 +108,8 @@ pub fn spec_to_pubsub_template_type<'a>(
         subscribe_channels,
         publish_channels,
         schema: joined_schemas,
+        title: &spec.info.title,
+        description: &spec.info.description,
     };
     Ok(pubsub_template)
 }

src/template_model/pubsub_template.rs

@@ -6,6 +6,8 @@ use std::string::*;
 
 #[derive(Serialize, Debug)]
 pub struct PubsubTemplate<'a> {
+    pub title: &'a String,
+    pub description: &'a Option<String>,
     pub server: &'a Server,
     pub subscribe_channels: Vec<(&'a String, &'a Operation)>,
     pub publish_channels: Vec<(&'a String, &'a Operation)>,

templates/Readme.md

@@ -0,0 +1,10 @@
+# {{.title}}
+{{if .description}}
+{{.description}}
+{{end}}
+
+## Documenation
+Open the documentation with the following command:
+``` 
+    cargo doc --no-deps --open
+```

templates/handler.rs

@@ -1,16 +1,19 @@
 use std::time;
 use async_nats::{Client, Message};
 use crate::publish_message;
+use serde::{Deserialize, Serialize};
 
 {{ .schema }}
 
  {{ range .subscribe_channels  }}
+    /// this handler is called when a message is received on {{ (index . 1).operationId }}
     pub fn handler_{{ (index . 1).operationId }}(message: Message) {
         println!("Received message {:#?}", message)
     }
 {{ end  }}
 
 {{ range .publish_channels }}
+    /// publish message to {{ (index . 1).operationId }}
     pub async fn producer_{{ (index . 1).operationId }}(client: &Client, channel: &str) {
         loop {
             tokio::time::sleep(time::Duration::from_secs(2)).await;