Doc: wip

martinreder · Mar 7, 2024 · ea82037 · ea82037
1 parent ad242c2
commit ea82037
Show file tree

Hide file tree

Showing 6 changed files with 150 additions and 86 deletions.
diff --git a/.prettierignore b/.prettierignore
@@ -1,2 +1,2 @@
 # Ignore markdown files in the docs
-/www/src/content/docs/docs/component/**/*.mdx
+/www/src/content/docs/docs/**/*.mdx
diff --git a/cmd/sst/main.go b/cmd/sst/main.go
@@ -172,36 +172,36 @@ func run() error {
 
 var Root = Command{
 	Name:        "sst",
-	Description: "deploy anything",
+	Description: "Deploy anything",
 	Flags: []Flag{
 		{
 			Name:        "stage",
 			Type:        "string",
-			Description: "the stage to deploy to",
+			Description: "The stage to deploy to",
 		},
 		{
 			Name:        "verbose",
 			Type:        "bool",
-			Description: "enable verbose logging",
+			Description: "Enable verbose logging",
 		},
 		{
 			Name:        "help",
 			Type:        "bool",
-			Description: "print help",
+			Description: "Print help",
 		},
 	},
 	Children: []*Command{
 		{
 			Name:        "version",
-			Description: "print the version",
+			Description: "Print the version",
 			Run: func(cli *Cli) error {
 				fmt.Printf("ion.%s\n", version)
 				return nil
 			},
 		},
 		{
 			Name:        "import",
-			Description: "import existing resource",
+			Description: "Import existing resource",
 			Args: []Argument{
 				{
 					Name:        "type",
@@ -223,7 +223,7 @@ var Root = Command{
 				{
 					Type:        "string",
 					Name:        "parent",
-					Description: "the parent resource",
+					Description: "The parent resource",
 				},
 			},
 			Run: func(cli *Cli) error {
@@ -253,17 +253,17 @@ var Root = Command{
 		},
 		{
 			Name:        "dev",
-			Description: "run in development mode",
+			Description: "Run in development mode",
 			Args:        []Argument{{Name: "command", Description: "The command to run"}},
 			Run:         CmdDev,
 		},
 		{
 			Name:        "secret",
-			Description: "manage secrets",
+			Description: "Manage secrets",
 			Children: []*Command{
 				{
 					Name:        "set",
-					Description: "set a secret",
+					Description: "Set a secret",
 					Args: []Argument{
 						{
 							Name:        "name",
@@ -310,7 +310,7 @@ var Root = Command{
 				},
 				{
 					Name:        "list",
-					Description: "list all secrets",
+					Description: "List all secrets",
 					Run: func(cli *Cli) error {
 						p, err := initProject(cli)
 						if err != nil {
@@ -334,7 +334,7 @@ var Root = Command{
 		{
 			Name:        "shell",
 			Args:        []Argument{{Name: "command", Description: "The command to run"}},
-			Description: "run command with all resource linked in environment",
+			Description: "Run command with all resource linked in environment",
 			Run: func(cli *Cli) error {
 				p, err := initProject(cli)
 				if err != nil {
@@ -416,7 +416,7 @@ var Root = Command{
 		},
 		{
 			Name:        "install",
-			Description: "install dependencies specified in sst.config.ts",
+			Description: "Install dependencies specified in sst.config.ts",
 			Run: func(cli *Cli) error {
 				cfgPath, err := project.Discover()
 				if err != nil {
@@ -448,7 +448,7 @@ var Root = Command{
 		},
 		{
 			Name:        "deploy",
-			Description: "deploy your application",
+			Description: "Deploy your application",
 			Run: func(cli *Cli) error {
 				p, err := initProject(cli)
 				if err != nil {
@@ -471,7 +471,7 @@ var Root = Command{
 		},
 		{
 			Name:        "remove",
-			Description: "remove your application",
+			Description: "Remove your application",
 			Run: func(cli *Cli) error {
 				p, err := initProject(cli)
 				if err != nil {
@@ -514,7 +514,7 @@ var Root = Command{
 		},
 		{
 			Name:        "cancel",
-			Description: "cancel any pending deploys",
+			Description: "Cancel any pending deploys",
 			Run: func(cli *Cli) error {
 				p, err := initProject(cli)
 				if err != nil {
@@ -567,7 +567,7 @@ var Root = Command{
 		},
 		{
 			Name:        "state",
-			Description: "manage state of your deployment",
+			Description: "Manage state of your deployment",
 			Children: []*Command{
 				{
 					Name:        "edit",

diff --git a/www/bun.lockb b/www/bun.lockb
diff --git a/www/generate.ts b/www/generate.ts
@@ -6,12 +6,10 @@ type CliCommand = {
   name: string;
   hidden: boolean;
   description: string;
-  args: { name: string; description: string; required: boolean }[] | null;
-  flags:
-    | { name: string; description: string; type: "string" | "bool" }[]
-    | null;
-  examples: { content: string; description: string }[] | null;
-  children: CliCommand[] | null;
+  args: { name: string; description: string; required: boolean }[];
+  flags: { name: string; description: string; type: "string" | "bool" }[];
+  examples: { content: string; description: string }[];
+  children: CliCommand[];
 };
 
 const cmd = process.argv[2];
@@ -67,7 +65,7 @@ async function generateCliDoc() {
 
   function renderCliGlobalFlags() {
     const lines: string[] = [];
-    if (!json.flags) return lines;
+    if (!json.flags.length) return lines;
 
     lines.push(``, `## Global Flags`);
 
@@ -79,7 +77,7 @@ async function generateCliDoc() {
         `<Segment>`,
         `<Section type="parameters">`,
         `<InlineSection>`,
-        `**Type** ${renderCliType(f.type)}`,
+        `**Type** ${renderCliFlagType(f.type)}`,
         `</InlineSection>`,
         `</Section>`,
         f.description,
@@ -91,37 +89,48 @@ async function generateCliDoc() {
 
   function renderCliCommands() {
     const lines: string[] = [];
-    if (!json.children) return lines;
+    if (!json.children.length) return lines;
 
     lines.push(``, `## Commands`);
 
-    for (const c of json.children.filter((c) => !c.hidden)) {
-      console.debug(` - command ${c.name}`);
-      lines.push(``, `### ${c.name}`, `<Segment>`);
+    for (const cmd of json.children.filter((cmd) => !cmd.hidden)) {
+      console.debug(` - command ${cmd.name}`);
+      lines.push(``, `### ${cmd.name}`, `<Segment>`);
+
+      // usage
+      if (cmd.children.length) {
+        lines.push(
+          `#### Usage`,
+          `<Section type="signature">`,
+          "```",
+          `sst ${renderCliCommandUsage(cmd)}`,
+          "```",
+          `</Section>`
+        );
+      }
 
       // args
-      // TODO render 'arg.required'
-      if (c.args) {
+      if (cmd.args.length) {
         lines.push(
           ``,
           `<Section type="parameters">`,
           `#### Args`,
-          ...c.args.flatMap((a) => [
-            `- <p><code class="key">${a.name}</code></p>`,
+          ...cmd.args.flatMap((a) => [
+            `- <p><code class="key">${renderCliArgName(a)}</code></p>`,
             a.description,
           ]),
           `</Section>`
         );
       }
 
       // flags
-      if (c.flags) {
+      if (cmd.flags.length) {
         lines.push(
           ``,
           `<Section type="parameters">`,
           `#### Flags`,
-          ...c.flags.flatMap((f) => [
-            `- <p><code class="key">${f.name}</code> ${renderCliType(
+          ...cmd.flags.flatMap((f) => [
+            `- <p><code class="key">${f.name}</code> ${renderCliFlagType(
               f.type
             )}</p>`,
             f.description,
@@ -131,24 +140,24 @@ async function generateCliDoc() {
       }
 
       // subcommands
-      if (c.children) {
+      if (cmd.children.length) {
         lines.push(
           ``,
           `<Section type="parameters">`,
           `#### Subcommands`,
-          ...c.children
+          ...cmd.children
             .filter((s) => !s.hidden)
             .flatMap((s) => [
-              `- <p>[<code class="key">${s.name}</code>](#${c.name}-${s.name})</p>`,
+              `- <p>[<code class="key">${s.name}</code>](#${cmd.name}-${s.name})</p>`,
             ]),
           `</Section>`
         );
       }
 
       // examples
       lines.push(
-        c.description,
-        ...(c.examples ?? []).flatMap((e) => [
+        cmd.description,
+        ...cmd.examples.flatMap((e) => [
           e.description,
           "```",
           e.content,
@@ -158,21 +167,32 @@ async function generateCliDoc() {
       );
 
       // subcommands details
-      (c.children ?? [])
-        .filter((s) => !s.hidden)
-        .flatMap((s) => {
+      cmd.children
+        .filter((subcmd) => !subcmd.hidden)
+        .flatMap((subcmd) => {
+          lines.push(
+            `<NestedTitle id="${cmd.name}-${subcmd.name}" Tag="h4" parent="${cmd.name} ">${subcmd.name}</NestedTitle>`,
+            `<Segment>`
+          );
+
+          // usage
           lines.push(
-            `<NestedTitle id="${c.name}-${s.name}" Tag="h4" parent="${c.name} ">${s.name}</NestedTitle>`,
-            `<Segment>`,
-            `<Section type="parameters">`
+            `**Usage**`,
+            `<Section type="signature">`,
+            "```",
+            `sst ${cmd.name} ${renderCliCommandUsage(subcmd)}`,
+            "```",
+            `</Section>`
           );
 
+          lines.push(`<Section type="parameters">`);
+
           // subcommand args
-          if (s.args) {
+          if (subcmd.args.length) {
             lines.push(
               `<InlineSection>`,
               `**Args**`,
-              ...s.args.flatMap((a) => [
+              ...subcmd.args.flatMap((a) => [
                 `- <p><code class="key">${a.name}</code></p>`,
                 a.description,
               ]),
@@ -181,11 +201,11 @@ async function generateCliDoc() {
           }
 
           // subcommand flags
-          if (s.flags) {
+          if (subcmd.flags.length) {
             lines.push(
               `<InlineSection>`,
               `**Args**`,
-              ...s.flags.flatMap((f) => [
+              ...subcmd.flags.flatMap((f) => [
                 `- <p><code class="key">${f.name}</code></p>`,
                 f.description,
               ]),
@@ -196,8 +216,8 @@ async function generateCliDoc() {
           // subcommands examples
           lines.push(
             `</Section>`,
-            s.description,
-            ...(s.examples ?? []).flatMap((e) => [
+            subcmd.description,
+            ...subcmd.examples.flatMap((e) => [
               e.description,
               "```",
               e.content,
@@ -210,11 +230,25 @@ async function generateCliDoc() {
     return lines;
   }
 
+  function renderCliArgName(prop: CliCommand["args"][number]) {
+    return `${prop.name}${prop.required ? "" : "?"}`;
+  }
+
+  function renderCliCommandUsage(command: CliCommand) {
+    const parts: string[] = [];
+
+    parts.push(command.name);
+    command.args.forEach((arg) =>
+      arg.required ? parts.push(`<${arg.name}>`) : parts.push(`[${arg.name}]`)
+    );
+    return parts.join(" ");
+  }
+
   function renderCliFooter() {
     return ["</div>"];
   }
 
-  function renderCliType(type: "string" | "bool") {
+  function renderCliFlagType(type: CliCommand["flags"][number]["type"]) {
     return `<code class="primitive">${
       type === "bool" ? "boolean" : type
     }</code>`;

diff --git a/www/package.json b/www/package.json
@@ -8,10 +8,10 @@
     "build": "bun generate && astro check && astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "generate-build-cli": "go run ../cmd/sst introspect > cli-doc.jsons",
-    "generate": "tsx generate.ts",
+    "generate": "bun generate-cli-json && tsx generate.ts",
     "generate-tsdoc": "tsx generate.ts tsdoc",
-    "generate-cli": "tsx generate.ts cli"
+    "generate-cli": "bun generate-cli-json && tsx generate.ts cli",
+    "generate-cli-json": "go run ../cmd/sst introspect > cli-doc.json"
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.0.5",