From 826fecaf957595f420a6ee319c54a183e9c5f40a Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Fri, 6 Dec 2024 09:17:52 -0600
Subject: [PATCH] docs: add more descriptions for the key and version flags

---
 documentation/commands/categories.md  | 40 ++++++++++++++++++----
 documentation/commands/changelogs.md  | 12 ++++++-
 documentation/commands/custompages.md | 12 ++++++-
 documentation/commands/docs.md        | 40 ++++++++++++++++++----
 documentation/commands/openapi.md     | 19 +++++++++--
 documentation/commands/versions.md    | 48 ++++++++++++++++++++++++---
 src/lib/flags.ts                      | 10 ++++--
 7 files changed, 158 insertions(+), 23 deletions(-)

diff --git a/documentation/commands/categories.md b/documentation/commands/categories.md
index 70021b722..85e9355de 100644
--- a/documentation/commands/categories.md
+++ b/documentation/commands/categories.md
@@ -15,9 +15,10 @@ USAGE
   $ rdme categories --key <value> [--version <value>]
 
 FLAGS
-  --key=<value>      (required) ReadMe Project API key
-  --version=<value>  Project version. If running command in a CI environment and this option is not passed, the main
-                     project version will be used.
+  --key=<value>      (required) An API key for your ReadMe project. Note that API authentication is required despite
+                     being omitted from the example usage. See our docs for more information:
+                     https://github.com/readmeio/rdme/tree/v9#authentication
+  --version=<value>  ReadMe project version
 
 DESCRIPTION
   Get all categories in your ReadMe project.
@@ -26,6 +27,19 @@ EXAMPLES
   Get all categories associated to your project version:
 
     $ rdme categories --version={project-version}
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
+
+  --version=<value>  ReadMe project version
+
+    Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
+    version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
 ```
 
 ## `rdme categories create TITLE`
@@ -42,11 +56,12 @@ ARGUMENTS
 FLAGS
   --categoryType=<option>  (required) Category type
                            <options: guide|reference>
-  --key=<value>            (required) ReadMe Project API key
+  --key=<value>            (required) An API key for your ReadMe project. Note that API authentication is required
+                           despite being omitted from the example usage. See our docs for more information:
+                           https://github.com/readmeio/rdme/tree/v9#authentication
   --preventDuplicates      Prevents the creation of a new category if there is an existing category with a matching
                            `categoryType` and `title`
-  --version=<value>        Project version. If running command in a CI environment and this option is not passed, the
-                           main project version will be used.
+  --version=<value>        ReadMe project version
 
 DESCRIPTION
   Create a category with the specified title and guide in your ReadMe project.
@@ -61,4 +76,17 @@ EXAMPLES
 
     $ rdme categories create <title> --categoryType={guide|reference} --version={project-version} \
       --preventDuplicates
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
+
+  --version=<value>  ReadMe project version
+
+    Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
+    version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
 ```
diff --git a/documentation/commands/changelogs.md b/documentation/commands/changelogs.md
index 8b971f4ab..b299e86fe 100644
--- a/documentation/commands/changelogs.md
+++ b/documentation/commands/changelogs.md
@@ -19,7 +19,9 @@ ARGUMENTS
 FLAGS
   --dryRun       Runs the command without creating/updating any changelogs in ReadMe. Useful for debugging.
   --github       Create a new GitHub Actions workflow for this command.
-  --key=<value>  (required) ReadMe Project API key
+  --key=<value>  (required) An API key for your ReadMe project. Note that API authentication is required despite being
+                 omitted from the example usage. See our docs for more information:
+                 https://github.com/readmeio/rdme/tree/v9#authentication
 
 DESCRIPTION
   Sync Markdown files to your ReadMe project as Changelog posts.
@@ -38,4 +40,12 @@ EXAMPLES
   dry run mode in our docs: https://docs.readme.com/main/docs/rdme#dry-run-mode
 
     $ rdme changelogs [path] --version={project-version} --dryRun
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
 ```
diff --git a/documentation/commands/custompages.md b/documentation/commands/custompages.md
index 045869f0c..6615c9516 100644
--- a/documentation/commands/custompages.md
+++ b/documentation/commands/custompages.md
@@ -19,7 +19,9 @@ ARGUMENTS
 FLAGS
   --dryRun       Runs the command without creating/updating any custom pages in ReadMe. Useful for debugging.
   --github       Create a new GitHub Actions workflow for this command.
-  --key=<value>  (required) ReadMe Project API key
+  --key=<value>  (required) An API key for your ReadMe project. Note that API authentication is required despite being
+                 omitted from the example usage. See our docs for more information:
+                 https://github.com/readmeio/rdme/tree/v9#authentication
 
 DESCRIPTION
   Sync Markdown/HTML files to your ReadMe project as Custom Pages.
@@ -38,4 +40,12 @@ EXAMPLES
   dry run mode in our docs: https://docs.readme.com/main/docs/rdme#dry-run-mode
 
     $ rdme custompages [path] --version={project-version} --dryRun
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
 ```
diff --git a/documentation/commands/docs.md b/documentation/commands/docs.md
index 2db00b5fe..1ac3970f5 100644
--- a/documentation/commands/docs.md
+++ b/documentation/commands/docs.md
@@ -20,9 +20,10 @@ ARGUMENTS
 FLAGS
   --dryRun           Runs the command without creating/updating any docs in ReadMe. Useful for debugging.
   --github           Create a new GitHub Actions workflow for this command.
-  --key=<value>      (required) ReadMe Project API key
-  --version=<value>  Project version. If running command in a CI environment and this option is not passed, the main
-                     project version will be used.
+  --key=<value>      (required) An API key for your ReadMe project. Note that API authentication is required despite
+                     being omitted from the example usage. See our docs for more information:
+                     https://github.com/readmeio/rdme/tree/v9#authentication
+  --version=<value>  ReadMe project version
 
 DESCRIPTION
   Sync Markdown files to your ReadMe project as Guides.
@@ -44,6 +45,19 @@ EXAMPLES
   dry run mode in our docs: https://docs.readme.com/main/docs/rdme#dry-run-mode
 
     $ rdme docs [path] --version={project-version} --dryRun
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
+
+  --version=<value>  ReadMe project version
+
+    Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
+    version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
 ```
 
 ## `rdme docs prune FOLDER`
@@ -61,9 +75,10 @@ FLAGS
   --confirm          Bypass the confirmation prompt. Useful for CI environments.
   --dryRun           Runs the command without deleting any docs in ReadMe. Useful for debugging.
   --github           Create a new GitHub Actions workflow for this command.
-  --key=<value>      (required) ReadMe Project API key
-  --version=<value>  Project version. If running command in a CI environment and this option is not passed, the main
-                     project version will be used.
+  --key=<value>      (required) An API key for your ReadMe project. Note that API authentication is required despite
+                     being omitted from the example usage. See our docs for more information:
+                     https://github.com/readmeio/rdme/tree/v9#authentication
+  --version=<value>  ReadMe project version
 
 DESCRIPTION
   Delete any docs from ReadMe if their slugs are not found in the target folder.
@@ -79,4 +94,17 @@ EXAMPLES
   Run with `--confirm` to bypass the confirmation prompt (useful for CI environments):
 
     $ rdme docs prune [path-to-directory-of-markdown] --confirm
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
+
+  --version=<value>  ReadMe project version
+
+    Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
+    version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
 ```
diff --git a/documentation/commands/openapi.md b/documentation/commands/openapi.md
index 0b39f4f77..381e015e0 100644
--- a/documentation/commands/openapi.md
+++ b/documentation/commands/openapi.md
@@ -28,15 +28,16 @@ FLAGS
   --github                    Create a new GitHub Actions workflow for this command.
   --id=<value>                Unique identifier for your API definition. Use this if you're re-uploading an existing API
                               definition.
-  --key=<value>               (required) ReadMe Project API key
+  --key=<value>               (required) An API key for your ReadMe project. Note that API authentication is required
+                              despite being omitted from the example usage. See our docs for more information:
+                              https://github.com/readmeio/rdme/tree/v9#authentication
   --raw                       Return the command results as a JSON object instead of a pretty output.
   --title=<value>             An override value for the `info.title` field in the API definition
   --update                    Bypasses the create/update prompt and automatically updates an existing API definition in
                               ReadMe.
   --useSpecVersion            Uses the version listed in the `info.version` field in the API definition for the project
                               version parameter.
-  --version=<value>           Project version. If running command in a CI environment and this option is not passed, the
-                              main project version will be used.
+  --version=<value>           ReadMe project version
   --workingDirectory=<value>  Working directory (for usage with relative external references)
 
 DESCRIPTION
@@ -98,10 +99,22 @@ EXAMPLES
     $ rdme openapi [url-or-local-path-to-file] --version={project-version} --update
 
 FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
+
   --update  Bypasses the create/update prompt and automatically updates an existing API definition in ReadMe.
 
     Bypasses the create/update prompt and automatically updates an existing API definition in ReadMe. Note that this
     flag only works if there's only one API definition associated with the current version.
+
+  --version=<value>  ReadMe project version
+
+    Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
+    version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
 ```
 
 ## `rdme openapi convert [SPEC]`
diff --git a/documentation/commands/versions.md b/documentation/commands/versions.md
index f15cd0101..00de1854c 100644
--- a/documentation/commands/versions.md
+++ b/documentation/commands/versions.md
@@ -17,7 +17,9 @@ USAGE
   $ rdme versions --key <value> [--version <value>]
 
 FLAGS
-  --key=<value>      (required) ReadMe Project API key
+  --key=<value>      (required) An API key for your ReadMe project. Note that API authentication is required despite
+                     being omitted from the example usage. See our docs for more information:
+                     https://github.com/readmeio/rdme/tree/v9#authentication
   --version=<value>  A specific project version to view.
 
 DESCRIPTION
@@ -31,6 +33,14 @@ EXAMPLES
   Get all information about a particular version:
 
     $ rdme versions --version={project-version}
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
 ```
 
 ## `rdme versions create VERSION`
@@ -54,7 +64,9 @@ FLAGS
   --fork=<value>         The semantic version which you'd like to fork from.
   --hidden=<option>      Should this version be hidden? The main version cannot be hidden.
                          <options: true|false>
-  --key=<value>          (required) ReadMe Project API key
+  --key=<value>          (required) An API key for your ReadMe project. Note that API authentication is required despite
+                         being omitted from the example usage. See our docs for more information:
+                         https://github.com/readmeio/rdme/tree/v9#authentication
   --main=<option>        Should this be the main version for your project?
                          <options: true|false>
 
@@ -71,6 +83,14 @@ EXAMPLES
 
     $ rdme versions create <version> --fork={version-fork} --main={true|false} --beta={true|false} \
       --deprecated={true|false} --hidden={true|false}
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
 ```
 
 ## `rdme versions delete [VERSION]`
@@ -85,7 +105,9 @@ ARGUMENTS
   VERSION  The version you'd like to delete.
 
 FLAGS
-  --key=<value>  (required) ReadMe Project API key
+  --key=<value>  (required) An API key for your ReadMe project. Note that API authentication is required despite being
+                 omitted from the example usage. See our docs for more information:
+                 https://github.com/readmeio/rdme/tree/v9#authentication
 
 DESCRIPTION
   Delete a version associated with your ReadMe project.
@@ -94,6 +116,14 @@ EXAMPLES
   Remove a specific version from your project, as well as all of the associated documentation:
 
     $ rdme versions delete <version>
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
 ```
 
 ## `rdme versions update [VERSION]`
@@ -116,7 +146,9 @@ FLAGS
                          <options: true|false>
   --hidden=<option>      Should this version be hidden? The main version cannot be hidden.
                          <options: true|false>
-  --key=<value>          (required) ReadMe Project API key
+  --key=<value>          (required) An API key for your ReadMe project. Note that API authentication is required despite
+                         being omitted from the example usage. See our docs for more information:
+                         https://github.com/readmeio/rdme/tree/v9#authentication
   --main=<option>        Should this be the main version for your project?
                          <options: true|false>
   --newVersion=<value>   What should the version be renamed to?
@@ -134,4 +166,12 @@ EXAMPLES
 
     $ rdme versions update <version> --newVersion={new-version-name} --main={true|false} --beta={true|false} \
       --deprecated={true|false} --hidden={true|false}
+
+FLAG DESCRIPTIONS
+  --key=<value>
+
+    An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
+    usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
+
+    ReadMe project API key
 ```
diff --git a/src/lib/flags.ts b/src/lib/flags.ts
index 16c355419..b3cf58336 100644
--- a/src/lib/flags.ts
+++ b/src/lib/flags.ts
@@ -8,7 +8,12 @@ export const githubFlag = Flags.boolean({ description: 'Create a new GitHub Acti
 /**
  * Used in any command where `key` is a `flag.
  */
-export const keyFlag = Flags.string({ description: 'ReadMe Project API key', required: true });
+export const keyFlag = Flags.string({
+  description: 'ReadMe project API key',
+  required: true,
+  summary:
+    'An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication',
+});
 
 /**
  * Used in the `openapi` family of commands where `title` is an option.
@@ -22,7 +27,8 @@ export const titleFlag = Flags.string({
  */
 export const versionFlag = Flags.string({
   description:
-    'Project version. If running command in a CI environment and this option is not passed, the main project version will be used.',
+    'Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions',
+  summary: 'ReadMe project version',
 });
 
 /**