feat: added source code links

Fixes #4

cli/src/cli/generate/markdown.rs

@@ -49,7 +49,7 @@ impl Markdown {
             ctx = ctx.with_multi(true);
             let commands = spec.cmd.all_subcommands().into_iter().filter(|c| !c.hide);
             for cmd in commands {
-                let md = ctx.render_cmd(cmd)?;
+                let md = ctx.render_cmd(&spec, cmd)?;
                 let dir = cmd
                     .full_cmd
                     .iter()

lib/src/docs/markdown/cmd.rs

@@ -1,10 +1,11 @@
 use crate::docs::markdown::renderer::MarkdownRenderer;
 use crate::error::UsageErr;
-use crate::SpecCommand;
+use crate::{Spec, SpecCommand};
 
 impl MarkdownRenderer {
-    pub fn render_cmd(&self, cmd: &SpecCommand) -> Result<String, UsageErr> {
+    pub fn render_cmd(&self, spec: &Spec, cmd: &SpecCommand) -> Result<String, UsageErr> {
         let mut ctx = self.clone();
+        ctx.insert("spec", spec);
         ctx.insert("cmd", cmd);
         ctx.render("cmd_template.md.tera")
     }
@@ -19,7 +20,7 @@ mod tests {
     #[test]
     fn test_render_markdown_cmd() {
         let ctx = MarkdownRenderer::new(&SPEC_KITCHEN_SINK).with_multi(true);
-        assert_snapshot!(ctx.render_cmd(&SPEC_KITCHEN_SINK.cmd).unwrap(), @r####"
+        assert_snapshot!(ctx.render_cmd(&SPEC_KITCHEN_SINK, &SPEC_KITCHEN_SINK.cmd).unwrap(), @r####"
         # `mycli`
 
         **Usage**: `mycli [FLAGS] <ARGS>… <SUBCOMMAND>`

lib/src/docs/markdown/renderer.rs

@@ -4,6 +4,7 @@ use crate::Spec;
 use itertools::Itertools;
 use serde::Serialize;
 use std::collections::HashMap;
+use xx::regex;
 
 #[derive(Debug, Clone)]
 pub struct MarkdownRenderer {
@@ -90,6 +91,34 @@ impl MarkdownRenderer {
                 Ok(value.into())
             },
         );
+        let path_re =
+            regex!(r"https://(github.com/[^/]+/[^/]+|gitlab.com/[^/]+/[^/]+/-)/blob/[^/]+/");
+        tera.register_function("source_code_link", |args: &HashMap<String, tera::Value>| {
+            let spec = args.get("spec").unwrap().as_object().unwrap();
+            let cmd = args.get("cmd").unwrap().as_object().unwrap();
+            let full_cmd = cmd.get("full_cmd").unwrap().as_array();
+            let source_code_link_template = spec
+                .get("source_code_link_template")
+                .map(|v| v.as_str().unwrap());
+            if let (Some(full_cmd), Some(source_code_link_template)) =
+                (full_cmd, source_code_link_template)
+            {
+                if full_cmd.is_empty() {
+                    return Ok("".into());
+                }
+                let mut ctx = tera::Context::new();
+                let path = full_cmd.iter().map(|v| v.as_str().unwrap()).join("/");
+                ctx.insert("spec", spec);
+                ctx.insert("cmd", cmd);
+                ctx.insert("path", &path);
+                let href = TERA.clone().render_str(source_code_link_template, &ctx)?;
+                let friendly = path_re.replace_all(&href, "").to_string();
+                let link = format!("[{friendly}]({href})");
+                Ok(link.into())
+            } else {
+                Ok("".into())
+            }
+        });
 
         Ok(tera.render(template_name, &self.tera_ctx())?)
     }

lib/src/docs/markdown/spec.rs

@@ -80,10 +80,14 @@ mod tests {
 
         **Usage**: `mycli plugin <SUBCOMMAND>`
 
+        **Source code**: [src/cli/plugin.rs](https://github.com/jdx/mise/blob/main/src/cli/plugin.rs)
+
         ## `mycli plugin install`
 
         **Usage**: `mycli plugin install [FLAGS] <plugin> <version>`
 
+        **Source code**: [src/cli/plugin/install.rs](https://github.com/jdx/mise/blob/main/src/cli/plugin/install.rs)
+
         ### Arguments
 
         #### `<plugin>`

lib/src/docs/markdown/templates/cmd_template.md.tera

@@ -1,3 +1,4 @@
+{%- set source_code_link = source_code_link(spec=spec, cmd=cmd) %}
 {%- if cmd.before_help_md %}{% set before_help = cmd.before_help_md %}{% elif cmd.before_help_long %}{% set before_help = cmd.before_help_long %}{% else %}{% set before_help = cmd.before_help %}{% endif %}
 {%- if cmd.help_md %}{% set help = cmd.help_md %}{% elif cmd.help_long %}{% set help = cmd.help_long %}{% else %}{% set help = cmd.help %}{% endif %}
 {%- if cmd.after_help_md %}{% set after_help = cmd.after_help_md %}{% elif cmd.after_help_long %}{% set after_help = cmd.after_help_long %}{% else %}{% set after_help = cmd.after_help %}{% endif %}
@@ -11,6 +12,10 @@
 {%- endif %}
 
 **Usage**: `{{ spec.bin ~ " " ~ cmd.usage | trim }}`
+{%- if source_code_link %}
+
+**Source code**: {{ source_code_link }}
+{%- endif %}
 
 {%- if cmd.aliases %}
 

lib/src/spec/mod.rs

@@ -36,6 +36,7 @@ pub struct Spec {
     pub usage: String,
     pub complete: IndexMap<String, SpecComplete>,
 
+    pub source_code_link_template: Option<String>,
     pub author: Option<String>,
     pub about: Option<String>,
     pub about_long: Option<String>,
@@ -100,6 +101,9 @@ impl Spec {
                 }
                 "version" => schema.version = Some(node.arg(0)?.ensure_string()?),
                 "author" => schema.author = Some(node.arg(0)?.ensure_string()?),
+                "source_code_link_template" => {
+                    schema.source_code_link_template = Some(node.arg(0)?.ensure_string()?)
+                }
                 "about" => schema.about = Some(node.arg(0)?.ensure_string()?),
                 "long_about" => schema.about_long = Some(node.arg(0)?.ensure_string()?),
                 "about_long" => schema.about_long = Some(node.arg(0)?.ensure_string()?),
@@ -158,6 +162,15 @@ impl Spec {
         if other.about.is_some() {
             self.about = other.about;
         }
+        if other.source_code_link_template.is_some() {
+            self.source_code_link_template = other.source_code_link_template;
+        }
+        if other.version.is_some() {
+            self.version = other.version;
+        }
+        if other.author.is_some() {
+            self.author = other.author;
+        }
         if other.about_long.is_some() {
             self.about_long = other.about_long;
         }
@@ -253,6 +266,16 @@ impl Display for Spec {
             node.push(KdlEntry::new(about.clone()));
             nodes.push(node);
         }
+        if let Some(source_code_link_template) = &self.source_code_link_template {
+            let mut node = KdlNode::new("source_code_link_template");
+            node.push(KdlEntry::new(source_code_link_template.clone()));
+            nodes.push(node);
+        }
+        if let Some(about_md) = &self.about_md {
+            let mut node = KdlNode::new("about_md");
+            node.push(KdlEntry::new(KdlValue::RawString(about_md.clone())));
+            nodes.push(node);
+        }
         if let Some(long_about) = &self.about_long {
             let mut node = KdlNode::new("long_about");
             node.push(KdlEntry::new(KdlValue::RawString(long_about.clone())));

lib/src/test.rs

@@ -11,6 +11,7 @@ macro_rules! spec {
 pub static SPEC_KITCHEN_SINK: Lazy<Spec> = Lazy::new(|| {
     spec! {r#"
 bin "mycli"
+source_code_link_template "https://github.com/jdx/mise/blob/main/src/cli/{{path}}.rs"
 arg "arg1" help="arg1 description"
 arg "arg2" help="arg2 description" default="default value" {
     choices "choice1" "choice2" "choice3"