fix: move usage out of header

jdx · Sep 29, 2024 · 9a43a72 · 9a43a72
1 parent 3a314d5
commit 9a43a72
Show file tree

Hide file tree

Showing 5 changed files with 27 additions and 9 deletions.
diff --git a/lib/src/docs/markdown/cmd.rs b/lib/src/docs/markdown/cmd.rs
@@ -20,7 +20,9 @@ mod tests {
     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####"
-        # `mycli [FLAGS] <ARGS>… <SUBCOMMAND>`
+        # `mycli`
+
+        **Usage**: `mycli [FLAGS] <ARGS>… <SUBCOMMAND>`
 
         ## Arguments
 

diff --git a/lib/src/docs/markdown/spec.rs b/lib/src/docs/markdown/spec.rs
@@ -26,7 +26,9 @@ mod tests {
     fn test_render_markdown_spec() {
         let ctx = MarkdownRenderer::new(&SPEC_KITCHEN_SINK);
         assert_snapshot!(ctx.render_spec().unwrap(), @r#####"
-        # `mycli [FLAGS] <ARGS>… <SUBCOMMAND>`
+        # `mycli`
+
+        **Usage**: `mycli [FLAGS] <ARGS>… <SUBCOMMAND>`
 
         ## Arguments
 
@@ -60,9 +62,13 @@ mod tests {
 
         ### `--shell <shell>`
 
-        ## `mycli plugin <SUBCOMMAND>`
+        ## `mycli plugin`
+
+        **Usage**: `mycli plugin <SUBCOMMAND>`
+
+        ## `mycli plugin install`
 
-        ## `mycli plugin install [FLAGS] <plugin> <version>`
+        **Usage**: `mycli plugin install [FLAGS] <plugin> <version>`
 
         ### Arguments
 

diff --git a/lib/src/docs/markdown/templates/cmd_template.md.tera b/lib/src/docs/markdown/templates/cmd_template.md.tera
@@ -1,14 +1,17 @@
 {%- 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 %}
+{%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
 {%- if multi -%}
-{{ "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ cmd.usage | trim }}`
+{{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ full_cmd | trim }}`
 {%- endif %}
 {%- if before_help %}
 
 {{ before_help | escape_md }}
 {%- endif %}
 
+**Usage**: `{{ spec.bin ~ " " ~ cmd.usage | trim }}`
+
 {%- if cmd.aliases %}
 
 **Aliases**: {{ cmd.aliases | join(sep=", ") }}

diff --git a/lib/src/docs/markdown/templates/index_template.md.tera b/lib/src/docs/markdown/templates/index_template.md.tera
@@ -1,9 +1,14 @@
 {%- set about = spec.about_long | default(value=spec.about) %}
 {%- set cmd = spec.cmd %}
-{{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ spec.cmd.usage | trim }}`
+{%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
+{{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ full_cmd | trim }}`
+
+**Usage**: `{{ spec.bin ~ " " ~ cmd.usage | trim }}`
 
 {%- if spec.version %}
-* **version**: {{ spec.version }}{% endif %}
+
+**Version**: {{ spec.version }}
+{%- endif %}
 
 {%- include "cmd_template.md.tera" %}
 

diff --git a/lib/src/docs/markdown/templates/spec_template.md.tera b/lib/src/docs/markdown/templates/spec_template.md.tera
@@ -1,6 +1,7 @@
 {%- set about = spec.about_long | default(value=spec.about) %}
 {%- set cmd = spec.cmd %}
-{{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ spec.cmd.usage | trim }}`
+{%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
+{{- "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ full_cmd | trim }}`
 
 {%- if spec.version %}
 * **version**: {{ spec.version }}{% endif %}
@@ -14,8 +15,9 @@
 {%- set header_level = header_level + 1 %}
 
 {%- for cmd in all_commands %}
+{%- set full_cmd = cmd.full_cmd | join(sep=" ") %}
 
-{{ "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ cmd.usage | trim }}`
+{{ "#" | repeat(count=header_level) }} `{{ spec.bin ~ " " ~ full_cmd | trim }}`
 
 {%- include "cmd_template.md.tera" %}
 {%- endfor -%}