feat: improving task docs

.markdownlintignore

@@ -1,6 +1,7 @@
-registry/
-target/
+/registry/
+/target/
 CHANGELOG.md
 docs/node_modules/
 node_modules/
 test/
+/tasks.md

.mise.toml

@@ -23,6 +23,7 @@ direnv = "latest"
 actionlint = "latest"
 ripgrep = "latest"
 "pipx:toml-sort" = "latest"
+usage = "latest"
 #python = { version = "latest", virtualenv = "{{env.HOME}}/.cache/venv" }
 #ruby = "3.1"
 
@@ -49,7 +50,12 @@ run = "cargo build --color always --all-features"
 [tasks."render:usage"]
 depends = ["build"]
 env = { CLICOLOR_FORCE = "0" }
-run = "mise usage > mise.usage.kdl"
+run = [
+    "mise usage > mise.usage.kdl",
+    "mise g task-docs > tasks.md",
+    "usage g md -f mise.usage.kdl -m --out-dir docs/cli --url-prefix /cli --html-encode",
+    "markdownlint --fix docs/cli",
+]
 
 [tasks."render:completions"]
 depends = ["build", "render:usage"]

.mise/tasks/filetask

@@ -3,6 +3,7 @@
 #USAGE flag "-f --force" help="Overwrite existing <file>"
 #USAGE flag "-u --user <user>" help="User to run as"
 #USAGE arg "<file>" help="The file to write" default="file.txt"
+#USAGE arg "<arg_with_default>" help="An arg with a default" default="mydefault"
 
 # mise description="This is a test build script"
 # mise depends=["lint", "build"]

Cargo.toml

@@ -115,8 +115,8 @@ tokio = { version = "1.37.0", features = [
 toml = { version = "0.8", features = ["parse"] }
 toml_edit = { version = "0.22", features = ["parse"] }
 url = "2.5.0"
-#usage-lib = { path = "../usage/lib" }
-usage-lib = { version = "0.8.0", features = ["clap", "docs"] }
+# usage-lib = { path = "../usage/lib", features = ["clap", "docs"] }
+usage-lib = { version = "0.8", features = ["clap", "docs"] }
 versions = { version = "6.2.0", features = ["serde"] }
 vfox = "0.1"
 walkdir = "2.5.0"

docs/.vitepress/config.ts

@@ -1,137 +1,133 @@
-import { defineConfig } from 'vitepress'
-import { Command, commands } from './cli_commands'
+import { defineConfig } from "vitepress";
+import { Command, commands } from "./cli_commands";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
   title: "mise-en-place",
   description: "mise-en-place documentation",
-  lang: 'en-US',
+  lang: "en-US",
   lastUpdated: true,
-  appearance: 'dark',
+  appearance: "dark",
   sitemap: {
-    hostname: 'https://mise.jdx.dev',
+    hostname: "https://mise.jdx.dev",
   },
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
-    outline: 'deep',
+    outline: "deep",
     nav: [
-      {text: 'Dev Tools', link: '/dev-tools/'},
-      {text: 'Environments', link: '/environments'},
-      {text: 'Tasks', link: '/tasks/'},
+      { text: "Dev Tools", link: "/dev-tools/" },
+      { text: "Environments", link: "/environments" },
+      { text: "Tasks", link: "/tasks/" },
     ],
     sidebar: [
-      {text: 'Getting Started', link: '/getting-started'},
-      {text: 'About', link: '/about'},
-      {text: 'Configuration', link: '/configuration'},
-      {text: 'Continuous Integration', link: '/continuous-integration'},
-      {text: 'Demo', link: '/demo'},
-      {text: 'FAQs', link: '/faq'},
-      {text: 'How I Use mise', link: '/how-i-use-mise'},
-      {text: 'IDE Integration', link: '/ide-integration'},
-      {text: 'Paranoid', link: '/paranoid'},
-      {text: 'Registry', link: '/registry'},
-      {text: 'Settings', link: '/settings'},
-      {text: 'Plugins', link: '/plugins'},
-      {text: 'Coming from rtx', link: '/rtx'},
-      {text: 'Team', link: '/team'},
-      {text: 'Contributing', link: '/contributing'},
-      {text: 'Tips & Tricks', link: '/tips-and-tricks'},
+      { text: "Getting Started", link: "/getting-started" },
+      { text: "About", link: "/about" },
+      { text: "Configuration", link: "/configuration" },
+      { text: "Continuous Integration", link: "/continuous-integration" },
+      { text: "Demo", link: "/demo" },
+      { text: "FAQs", link: "/faq" },
+      { text: "How I Use mise", link: "/how-i-use-mise" },
+      { text: "IDE Integration", link: "/ide-integration" },
+      { text: "Paranoid", link: "/paranoid" },
+      { text: "Registry", link: "/registry" },
+      { text: "Settings", link: "/settings" },
+      { text: "Plugins", link: "/plugins" },
+      { text: "Coming from rtx", link: "/rtx" },
+      { text: "Team", link: "/team" },
+      { text: "Contributing", link: "/contributing" },
+      { text: "Tips & Tricks", link: "/tips-and-tricks" },
       {
-        text: 'Dev Tools',
-        link: '/dev-tools/',
+        text: "Dev Tools",
+        link: "/dev-tools/",
         items: [
-          {text: 'Aliases', link: '/dev-tools/aliases'},
-          {text: 'Comparison to asdf', link: '/dev-tools/comparison-to-asdf'},
-          {text: 'Shims', link: '/dev-tools/shims'},
+          { text: "Aliases", link: "/dev-tools/aliases" },
+          { text: "Comparison to asdf", link: "/dev-tools/comparison-to-asdf" },
+          { text: "Shims", link: "/dev-tools/shims" },
           {
-            text: 'Backends',
-            link: '/dev-tools/backends/',
+            text: "Backends",
+            link: "/dev-tools/backends/",
             items: [
-              {text: 'asdf', link: '/dev-tools/backends/asdf'},
-              {text: 'cargo', link: '/dev-tools/backends/cargo'},
-              {text: 'go', link: '/dev-tools/backends/go'},
-              {text: 'npm', link: '/dev-tools/backends/npm'},
-              {text: 'pipx', link: '/dev-tools/backends/pipx'},
-              {text: 'spm', link: '/dev-tools/backends/spm'},
-              {text: 'ubi', link: '/dev-tools/backends/ubi'},
-              {text: 'vfox', link: '/dev-tools/backends/vfox'},
-            ]
-          }
+              { text: "asdf", link: "/dev-tools/backends/asdf" },
+              { text: "cargo", link: "/dev-tools/backends/cargo" },
+              { text: "go", link: "/dev-tools/backends/go" },
+              { text: "npm", link: "/dev-tools/backends/npm" },
+              { text: "pipx", link: "/dev-tools/backends/pipx" },
+              { text: "spm", link: "/dev-tools/backends/spm" },
+              { text: "ubi", link: "/dev-tools/backends/ubi" },
+              { text: "vfox", link: "/dev-tools/backends/vfox" },
+            ],
+          },
         ],
       },
       {
-        text: 'Environments',
-        link: '/environments',
+        text: "Environments",
+        link: "/environments",
         items: [
-          {text: 'direnv', link: '/direnv'},
-          {text: 'Profiles', link: '/profiles'},
-          {text: 'Templates', link: '/templates'},
+          { text: "direnv", link: "/direnv" },
+          { text: "Profiles", link: "/profiles" },
+          { text: "Templates", link: "/templates" },
         ],
       },
       {
-        text: 'Tasks',
-        link: '/tasks/',
+        text: "Tasks",
+        link: "/tasks/",
         items: [
-          {text: 'Running Tasks', link: '/tasks/running-tasks'},
-          {text: 'File Tasks', link: '/tasks/file-tasks'},
-          {text: 'TOML Tasks', link: '/tasks/toml-tasks'},
+          { text: "Running Tasks", link: "/tasks/running-tasks" },
+          { text: "File Tasks", link: "/tasks/file-tasks" },
+          { text: "TOML Tasks", link: "/tasks/toml-tasks" },
         ],
       },
       {
-        text: 'Languages',
+        text: "Languages",
         items: [
-          {text: 'Bun', link: '/lang/bun'},
-          {text: 'Deno', link: '/lang/deno'},
-          {text: 'Erlang', link: '/lang/erlang'},
-          {text: 'Go', link: '/lang/go'},
-          {text: 'Java', link: '/lang/java'},
-          {text: 'Node.js', link: '/lang/node'},
-          {text: 'Python', link: '/lang/python'},
-          {text: 'Ruby', link: '/lang/ruby'},
-          {text: 'Rust', link: '/lang/rust'},
-        ]
+          { text: "Bun", link: "/lang/bun" },
+          { text: "Deno", link: "/lang/deno" },
+          { text: "Erlang", link: "/lang/erlang" },
+          { text: "Go", link: "/lang/go" },
+          { text: "Java", link: "/lang/java" },
+          { text: "Node.js", link: "/lang/node" },
+          { text: "Python", link: "/lang/python" },
+          { text: "Ruby", link: "/lang/ruby" },
+          { text: "Rust", link: "/lang/rust" },
+        ],
       },
       {
-        text: 'Internals',
+        text: "Internals",
         items: [
-          {text: 'Cache Behavior', link: '/cache-behavior'},
-          {text: 'Directory Structure', link: '/directories'},
-          {text: 'Project Roadmap', link: '/project-roadmap'},
+          { text: "Cache Behavior", link: "/cache-behavior" },
+          { text: "Directory Structure", link: "/directories" },
+          { text: "Project Roadmap", link: "/project-roadmap" },
         ],
       },
       {
-        text: 'CLI Reference',
-        link: '/cli/',
-        items: [
-          {text: 'Global Flags', link: '/cli/global-flags'},
-          ...cliReference(commands),
-        ]
+        text: "CLI Reference",
+        link: "/cli/",
+        items: cliReference(commands),
       },
     ],
 
-    socialLinks: [
-      {icon: 'github', link: 'https://github.com/jdx/mise'}
-    ],
+    socialLinks: [{ icon: "github", link: "https://github.com/jdx/mise" }],
 
     editLink: {
-      pattern: 'https://github.com/jdx/mise/edit/main/docs/:path',
+      pattern: "https://github.com/jdx/mise/edit/main/docs/:path",
     },
     search: {
-      provider: 'algolia',
+      provider: "algolia",
       options: {
-        indexName: 'rtx',
-        appId: '1452G4RPSJ',
-        apiKey: 'ad09b96a7d2a30eddc2771800da7a1cf',
+        indexName: "rtx",
+        appId: "1452G4RPSJ",
+        apiKey: "ad09b96a7d2a30eddc2771800da7a1cf",
         insights: true,
-      }
+      },
     },
     footer: {
-      message: 'Licensed under the MIT License. Maintained by <a href="https://github.com/jdx">@jdx</a> and <a href="https://github.com/jdx/mise/graphs/contributors">friends</a>.',
+      message:
+        'Licensed under the MIT License. Maintained by <a href="https://github.com/jdx">@jdx</a> and <a href="https://github.com/jdx/mise/graphs/contributors">friends</a>.',
       copyright: 'Copyright © 2024 <a href="https://github.com/jdx">@jdx</a>',
     },
     carbonAds: {
-      code: 'CWYIPKQN',
-      placement: 'misejdxdev',
+      code: "CWYIPKQN",
+      placement: "misejdxdev",
     },
   },
   markdown: {
@@ -141,37 +137,44 @@ export default defineConfig({
   },
   head: [
     [
-      'script',
-      {async: '', src: 'https://www.googletagmanager.com/gtag/js?id=G-B69G389C8T'}
+      "script",
+      {
+        async: "",
+        src: "https://www.googletagmanager.com/gtag/js?id=G-B69G389C8T",
+      },
     ],
     [
-      'script',
+      "script",
       {},
       `window.dataLayer = window.dataLayer || [];
       function gtag(){dataLayer.push(arguments);}
       gtag('js', new Date());
-      gtag('config', 'G-B69G389C8T');`
-    ]
+      gtag('config', 'G-B69G389C8T');`,
+    ],
   ],
-})
+});
 
 function cliReference(commands: { [key: string]: Command }) {
   return Object.keys(commands)
     .map((name) => [name, commands[name]] as [string, Command])
     .filter(([name, command]) => command.hide !== true)
     .map(([name, command]) => {
       const x: any = {
-        text: name,
+        text: `mise ${name}`,
       };
       if (command.subcommands) {
         x.collapsed = true;
-        x.items = Object.keys(command.subcommands).map((subcommand) => ({
-          text: subcommand,
-          link: `/cli/${name}/${subcommand}`,
-        }));
+        x.items = Object.keys(command.subcommands)
+          .filter(
+            (subcommand) => command.subcommands![subcommand].hide !== true,
+          )
+          .map((subcommand) => ({
+            text: `mise ${name} ${subcommand}`,
+            link: `/cli/${name}/${subcommand}`,
+          }));
       } else {
         x.link = `/cli/${name}`;
       }
       return x;
-    })
+    });
 }