Skip to content

Commit 15447c5

Browse files
kanadguptakanadgupta
authored
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.
1 parent a69feb1 commit 15447c5

10 files changed

Lines changed: 202 additions & 114 deletions

File tree

‎README.md‎

Lines changed: 28 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -37,13 +37,39 @@ npm run build && npm run build:docs
3737
<!-- prettier-ignore-start -->
3838
<!-- toc -->
3939
* [Table of Contents](#table-of-contents)
40+
* [Quick Start](#quick-start)
4041
* [CLI Configuration](#cli-configuration)
4142
* [GitHub Actions Configuration](#github-actions-configuration)
42-
* [Usage](#usage)
4343
* [Command Topics](#command-topics)
4444
<!-- tocstop -->
4545
<!-- prettier-ignore-end -->
4646

47+
# Quick Start
48+
49+
Install the CLI ([see here for more setup options](#setup)):
50+
51+
```sh
52+
npm install -g rdme
53+
```
54+
55+
Validate an OpenAPI file in your working directory or any subdirectories ([see here for all command topics](#command-topics)):
56+
57+
```sh
58+
rdme openapi validate
59+
```
60+
61+
Every command has a help page, which you can access in [our docs](./documentation/commands) or via the CLI:
62+
63+
```sh
64+
rdme openapi validate --help
65+
```
66+
67+
To view the current version of `rdme` (helpful for troubleshooting and bug reports):
68+
69+
```sh
70+
rdme --version
71+
```
72+
4773
# CLI Configuration
4874

4975
## Setup
@@ -119,7 +145,7 @@ rdme openapi
119145
> [!NOTE]
120146
> 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).
121147
122-
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:
148+
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:
123149

124150
```sh
125151
rdme openapi --github
@@ -129,39 +155,6 @@ This will run through the `openapi` command, ask you a few quick questions, and
129155

130156
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).
131157

132-
# Usage
133-
134-
<!--
135-
This section is autogenerated using `oclif` and is regenerated with every release.
136-
137-
If you wish to preview these changes locally, run the following:
138-
139-
```
140-
npm run build && npm run build:docs
141-
```
142-
-->
143-
144-
<!-- prettier-ignore-start -->
145-
<!-- usage -->
146-
```sh-session
147-
$ npm install -g rdme
148-
$ rdme COMMAND
149-
running command...
150-
$ rdme (--version)
151-
rdme/9.0.0-next.35 linux-x64 node-v20.18.1
152-
$ rdme --help [COMMAND]
153-
USAGE
154-
$ rdme COMMAND
155-
...
156-
```
157-
<!-- usagestop -->
158-
<!-- prettier-ignore-end -->
159-
160-
## Common `rdme` Options
161-
162-
- `--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.
163-
- `--version <string>`: Your project version. See [our docs](https://docs.readme.com/docs/versions) for more information.
164-
165158
<!--
166159
This section is autogenerated using `oclif` and is regenerated with every release.
167160

‎documentation/commands/categories.md‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,10 @@ USAGE
1515
$ rdme categories --key <value> [--version <value>]
1616
1717
FLAGS
18-
--key=<value> (required) ReadMe Project API key
19-
--version=<value> Project version. If running command in a CI environment and this option is not passed, the main
20-
project version will be used.
18+
--key=<value> (required) An API key for your ReadMe project. Note that API authentication is required despite
19+
being omitted from the example usage. See our docs for more information:
20+
https://github.com/readmeio/rdme/tree/v9#authentication
21+
--version=<value> ReadMe project version
2122
2223
DESCRIPTION
2324
Get all categories in your ReadMe project.
@@ -26,6 +27,19 @@ EXAMPLES
2627
Get all categories associated to your project version:
2728
2829
$ rdme categories --version={project-version}
30+
31+
FLAG DESCRIPTIONS
32+
--key=<value>
33+
34+
An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
35+
usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
36+
37+
ReadMe project API key
38+
39+
--version=<value> ReadMe project version
40+
41+
Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
42+
version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
2943
```
3044

3145
## `rdme categories create TITLE`
@@ -42,11 +56,12 @@ ARGUMENTS
4256
FLAGS
4357
--categoryType=<option> (required) Category type
4458
<options: guide|reference>
45-
--key=<value> (required) ReadMe Project API key
59+
--key=<value> (required) An API key for your ReadMe project. Note that API authentication is required
60+
despite being omitted from the example usage. See our docs for more information:
61+
https://github.com/readmeio/rdme/tree/v9#authentication
4662
--preventDuplicates Prevents the creation of a new category if there is an existing category with a matching
4763
`categoryType` and `title`
48-
--version=<value> Project version. If running command in a CI environment and this option is not passed, the
49-
main project version will be used.
64+
--version=<value> ReadMe project version
5065
5166
DESCRIPTION
5267
Create a category with the specified title and guide in your ReadMe project.
@@ -61,4 +76,17 @@ EXAMPLES
6176
6277
$ rdme categories create <title> --categoryType={guide|reference} --version={project-version} \
6378
--preventDuplicates
79+
80+
FLAG DESCRIPTIONS
81+
--key=<value>
82+
83+
An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
84+
usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
85+
86+
ReadMe project API key
87+
88+
--version=<value> ReadMe project version
89+
90+
Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
91+
version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
6492
```

‎documentation/commands/changelogs.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ ARGUMENTS
1919
FLAGS
2020
--dryRun Runs the command without creating/updating any changelogs in ReadMe. Useful for debugging.
2121
--github Create a new GitHub Actions workflow for this command.
22-
--key=<value> (required) ReadMe Project API key
22+
--key=<value> (required) An API key for your ReadMe project. Note that API authentication is required despite being
23+
omitted from the example usage. See our docs for more information:
24+
https://github.com/readmeio/rdme/tree/v9#authentication
2325
2426
DESCRIPTION
2527
Sync Markdown files to your ReadMe project as Changelog posts.
@@ -38,4 +40,12 @@ EXAMPLES
3840
dry run mode in our docs: https://docs.readme.com/main/docs/rdme#dry-run-mode
3941
4042
$ rdme changelogs [path] --version={project-version} --dryRun
43+
44+
FLAG DESCRIPTIONS
45+
--key=<value>
46+
47+
An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
48+
usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
49+
50+
ReadMe project API key
4151
```

‎documentation/commands/custompages.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@ ARGUMENTS
1919
FLAGS
2020
--dryRun Runs the command without creating/updating any custom pages in ReadMe. Useful for debugging.
2121
--github Create a new GitHub Actions workflow for this command.
22-
--key=<value> (required) ReadMe Project API key
22+
--key=<value> (required) An API key for your ReadMe project. Note that API authentication is required despite being
23+
omitted from the example usage. See our docs for more information:
24+
https://github.com/readmeio/rdme/tree/v9#authentication
2325
2426
DESCRIPTION
2527
Sync Markdown/HTML files to your ReadMe project as Custom Pages.
@@ -38,4 +40,12 @@ EXAMPLES
3840
dry run mode in our docs: https://docs.readme.com/main/docs/rdme#dry-run-mode
3941
4042
$ rdme custompages [path] --version={project-version} --dryRun
43+
44+
FLAG DESCRIPTIONS
45+
--key=<value>
46+
47+
An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
48+
usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
49+
50+
ReadMe project API key
4151
```

‎documentation/commands/docs.md‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,9 +20,10 @@ ARGUMENTS
2020
FLAGS
2121
--dryRun Runs the command without creating/updating any docs in ReadMe. Useful for debugging.
2222
--github Create a new GitHub Actions workflow for this command.
23-
--key=<value> (required) ReadMe Project API key
24-
--version=<value> Project version. If running command in a CI environment and this option is not passed, the main
25-
project version will be used.
23+
--key=<value> (required) An API key for your ReadMe project. Note that API authentication is required despite
24+
being omitted from the example usage. See our docs for more information:
25+
https://github.com/readmeio/rdme/tree/v9#authentication
26+
--version=<value> ReadMe project version
2627
2728
DESCRIPTION
2829
Sync Markdown files to your ReadMe project as Guides.
@@ -44,6 +45,19 @@ EXAMPLES
4445
dry run mode in our docs: https://docs.readme.com/main/docs/rdme#dry-run-mode
4546
4647
$ rdme docs [path] --version={project-version} --dryRun
48+
49+
FLAG DESCRIPTIONS
50+
--key=<value>
51+
52+
An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
53+
usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
54+
55+
ReadMe project API key
56+
57+
--version=<value> ReadMe project version
58+
59+
Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
60+
version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
4761
```
4862

4963
## `rdme docs prune FOLDER`
@@ -61,9 +75,10 @@ FLAGS
6175
--confirm Bypass the confirmation prompt. Useful for CI environments.
6276
--dryRun Runs the command without deleting any docs in ReadMe. Useful for debugging.
6377
--github Create a new GitHub Actions workflow for this command.
64-
--key=<value> (required) ReadMe Project API key
65-
--version=<value> Project version. If running command in a CI environment and this option is not passed, the main
66-
project version will be used.
78+
--key=<value> (required) An API key for your ReadMe project. Note that API authentication is required despite
79+
being omitted from the example usage. See our docs for more information:
80+
https://github.com/readmeio/rdme/tree/v9#authentication
81+
--version=<value> ReadMe project version
6782
6883
DESCRIPTION
6984
Delete any docs from ReadMe if their slugs are not found in the target folder.
@@ -79,4 +94,17 @@ EXAMPLES
7994
Run with `--confirm` to bypass the confirmation prompt (useful for CI environments):
8095
8196
$ rdme docs prune [path-to-directory-of-markdown] --confirm
97+
98+
FLAG DESCRIPTIONS
99+
--key=<value>
100+
101+
An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
102+
usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
103+
104+
ReadMe project API key
105+
106+
--version=<value> ReadMe project version
107+
108+
Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
109+
version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
82110
```

‎documentation/commands/openapi.md‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,16 @@ FLAGS
2828
--github Create a new GitHub Actions workflow for this command.
2929
--id=<value> Unique identifier for your API definition. Use this if you're re-uploading an existing API
3030
definition.
31-
--key=<value> (required) ReadMe Project API key
31+
--key=<value> (required) An API key for your ReadMe project. Note that API authentication is required
32+
despite being omitted from the example usage. See our docs for more information:
33+
https://github.com/readmeio/rdme/tree/v9#authentication
3234
--raw Return the command results as a JSON object instead of a pretty output.
3335
--title=<value> An override value for the `info.title` field in the API definition
3436
--update Bypasses the create/update prompt and automatically updates an existing API definition in
3537
ReadMe.
3638
--useSpecVersion Uses the version listed in the `info.version` field in the API definition for the project
3739
version parameter.
38-
--version=<value> Project version. If running command in a CI environment and this option is not passed, the
39-
main project version will be used.
40+
--version=<value> ReadMe project version
4041
--workingDirectory=<value> Working directory (for usage with relative external references)
4142
4243
DESCRIPTION
@@ -98,10 +99,22 @@ EXAMPLES
9899
$ rdme openapi [url-or-local-path-to-file] --version={project-version} --update
99100
100101
FLAG DESCRIPTIONS
102+
--key=<value>
103+
104+
An API key for your ReadMe project. Note that API authentication is required despite being omitted from the example
105+
usage. See our docs for more information: https://github.com/readmeio/rdme/tree/v9#authentication
106+
107+
ReadMe project API key
108+
101109
--update Bypasses the create/update prompt and automatically updates an existing API definition in ReadMe.
102110
103111
Bypasses the create/update prompt and automatically updates an existing API definition in ReadMe. Note that this
104112
flag only works if there's only one API definition associated with the current version.
113+
114+
--version=<value> ReadMe project version
115+
116+
Your ReadMe project version. If running command in a CI environment and this option is not passed, the main project
117+
version will be used. See our docs for more information: https://docs.readme.com/main/docs/versions
105118
```
106119

107120
## `rdme openapi convert [SPEC]`

0 commit comments

Comments
 (0)