feat!: final v9 touchups (#1106)

## 🧰 Changes a few final touchups before we ship v9 🚀 - [x] adds a deprecation notice to `rdme openapi` - [x] removes the usage section from our docs in favor of a quick start - [x] improves the documentation for our `--key` and `--version` flags - [x] removes all `v10` migration guide language for now and adds a placeholder. i have a separate PR ([#1107](#1107)) that adds that language back when we're ready. i figured i'd chunk this out so we can ship v9 without having to finalize the new `rdme openapi` command replacement. ## 🧬 QA & Testing Do these doc changes look sound? --- BREAKING CHANGE: `rdme openapi` is deprecated and will be replaced in `rdme@10` by a command with a simpler flag setup based on community feedback.
readmeio · Dec 6, 2024 · 15447c5 · 15447c5
1 parent a69feb1
commit 15447c5
Show file tree

Hide file tree

Showing 10 changed files with 202 additions and 114 deletions.
diff --git a/README.md b/README.md
@@ -37,13 +37,39 @@ npm run build && npm run build:docs
 <!-- prettier-ignore-start -->
 <!-- toc -->
 * [Table of Contents](#table-of-contents)
+* [Quick Start](#quick-start)
 * [CLI Configuration](#cli-configuration)
 * [GitHub Actions Configuration](#github-actions-configuration)
-* [Usage](#usage)
 * [Command Topics](#command-topics)
 <!-- tocstop -->
 <!-- prettier-ignore-end -->
 
+# Quick Start
+
+Install the CLI ([see here for more setup options](#setup)):
+
+```sh
+npm install -g rdme
+```
+
+Validate an OpenAPI file in your working directory or any subdirectories ([see here for all command topics](#command-topics)):
+
+```sh
+rdme openapi validate
+```
+
+Every command has a help page, which you can access in [our docs](./documentation/commands) or via the CLI:
+
+```sh
+rdme openapi validate --help
+```
+
+To view the current version of `rdme` (helpful for troubleshooting and bug reports):
+
+```sh
+rdme --version
+```
+
 # CLI Configuration
 
 ## Setup
@@ -119,7 +145,7 @@ rdme openapi
 > [!NOTE]
 > For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/rdme#github-actions-usage).
 
-For usage in [GitHub Actions](https://docs.github.com/actions), you can create a new GitHub Actions workflow file by including the `--github` flag with the command you wish to run in GitHub Actions. For example:
+For usage in [GitHub Actions](https://docs.github.com/actions), you can create a new GitHub Actions workflow file by installing the CLI on your local machine and running the the command you wish to run in GitHub Actions, along with the `--github` flag. For example:
 
 ```sh
 rdme openapi --github
@@ -129,39 +155,6 @@ This will run through the `openapi` command, ask you a few quick questions, and
 
 You can see examples featuring the latest version in [our docs](https://docs.readme.com/docs/rdme#github-actions-examples). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot).
 
-# Usage
-
-<!--
-This section is autogenerated using `oclif` and is regenerated with every release.
-
-If you wish to preview these changes locally, run the following:
-
-```
-npm run build && npm run build:docs
-```
--->
-
-<!-- prettier-ignore-start -->
-<!-- usage -->
-```sh-session
-$ npm install -g rdme
-$ rdme COMMAND
-running command...
-$ rdme (--version)
-rdme/9.0.0-next.35 linux-x64 node-v20.18.1
-$ rdme --help [COMMAND]
-USAGE
-  $ rdme COMMAND
-...
-```
-<!-- usagestop -->
-<!-- prettier-ignore-end -->
-
-## Common `rdme` Options
-
-- `--key <string>`: The API key associated with your ReadMe project. Note that most of the commands below require API key authentication, even though the `--key` flag is omitted from the examples. See the [Authentication](#authentication) section above for more information.
-- `--version <string>`: Your project version. See [our docs](https://docs.readme.com/docs/versions) for more information.
-
 <!--
 This section is autogenerated using `oclif` and is regenerated with every release.
 

diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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]`