docs: updated commands documentation (issue 1429) and minor corrections. #1560

dianacheung · 2024-05-13T07:40:11Z

What/Why/How?

Updated commands documentation per issue 1429 and also made minor changes for correction and consistency.

Reference

#1429

Testing

Ran redocly preview for local development.
Ran spelling check.
Ran vale.
Ran mlc.
Ran markdownlint.

changeset-bot · 2024-05-13T07:40:14Z

⚠️ No Changeset found

Latest commit: 91f6fd4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

…ions, ran prettier

dianacheung · 2024-05-13T08:26:15Z

Ran prettier on the commands md files.

dianacheung · 2024-05-19T20:43:35Z

Hi @lornajane, docs PR still awaiting review and approval from Redocly/technical-writers. Thanks in advance.

lornajane · 2024-05-20T08:48:29Z

Thanks @dianacheung ! I see it and it's on my list, we will review when we can.

HCloward · 2024-05-21T13:30:40Z

docs/commands/build-docs.md


 ```bash
 redocly build-docs openapi.yaml
 ```

-In this case, the `build-docs` command builds the API at the path provided.
+In this case, the `build-docs` command builds the API description that was passed to the command.
 The configuration file is ignored.


Suggested change

The configuration file is ignored.

Even if a configuration file exists, the command does not check for APIs listed in it.

HCloward · 2024-05-21T15:05:49Z

docs/commands/build-docs.md


 ```yaml Configuration file
 apis:
  games@v1:
    root: ./openapi/api-description.json
 ```

-The `build-docs` command uses any additional configurations provided in the file.
+You can generate a build by giving the API alias name, as shown below:


Suggested change

You can generate a build by giving the API alias name, as shown below:

You can generate a build by including the API name with the command, as in the following example:

HCloward · 2024-05-21T15:32:08Z

docs/commands/build-docs.md

+```
+
+In this case, after resolving the path behind the `games@v1` name, `build-docs` generates a build of the `api-description.json` file. For this approach, the Redocly configuration file is mandatory.
+Any additional configurations provided in the file are used by the command.


Suggested change

Any additional configurations provided in the file are used by the command.

Any additional configurations provided in the file are also used by the command.

HCloward · 2024-05-21T15:33:42Z

docs/commands/build-docs.md


-### Custom configuration file
+### Use custom configuration file


Suggested change

### Use custom configuration file

### Use alternative file path

HCloward · 2024-05-21T15:34:05Z

docs/commands/build-docs.md


 By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.

 ```bash
 redocly build-docs --config=./another/directory/config.yaml
 ```

-### `theme.openapi` example
+### Use theme.openapi option


Suggested change

### Use theme.openapi option

### Hide search

HCloward · 2024-05-21T15:36:21Z

docs/commands/build-docs.md


-Build docs with hidden search box:
+The following command uses the optional `--theme.openapi` argument to build docs with hidden search box:


Suggested change

The following command uses the optional `--theme.openapi` argument to build docs with hidden search box:

The following command uses the optional `--theme.openapi` argument to build docs with the search box hidden:

HCloward · 2024-05-21T15:37:17Z

docs/commands/build-docs.md


 ```bash
 redocly build-docs openapi.yaml --theme.openapi.disableSearch
 ```

-### `templateOptions` example
+### Use templateOptions option


Suggested change

### Use templateOptions option

### Use a custom template

HCloward · 2024-05-21T15:45:30Z

docs/commands/build-docs.md


-Build docs using a custom Handlebars template and add custom `templateOptions`:
+The following command uses the optional `--templateOptions` argument to build docs using a custom Handlebars template and add a custom `templateOptions` object:


Suggested change

The following command uses the optional `--templateOptions` argument to build docs using a custom Handlebars template and add a custom `templateOptions` object:

The following command builds docs using a custom Handlebars template and adds metadata to the meta tag in the head of the page using `templateOptions`:

HCloward · 2024-05-21T15:52:36Z

docs/commands/bundle.md

@@ -73,7 +77,7 @@ redocly bundle --dereferenced --output dist --ext json openapi/openapi.yaml open
 JSON output only works when there are no circular references.
 {% /admonition %}

-### Custom configuration file
+### Use custom configuration file


Suggested change

### Use custom configuration file

### Use alternative file path

HCloward · 2024-05-21T15:54:50Z

docs/commands/check-config.md

 | --lint-config | string | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`. Default value is `error`. |

 ## Examples

-### Default configuration file
+### Use default configuration file


Suggested change

### Use default configuration file

### Use default location for configuration file

HCloward · 2024-05-21T15:55:05Z

docs/commands/check-config.md


 By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory.

 ```bash
 redocly check-config
 ```

-### Custom configuration file
+### Use custom configuration file


Suggested change

### Use custom configuration file

### Use alternative filepath

HCloward · 2024-05-21T15:59:39Z

docs/commands/completion.md

@@ -14,13 +14,15 @@ The output is a script for you to copy and paste, and add to the configuration f



hmm, for some reason this file is not included in the sidebar navigation menu. I will need to check with team to find out why. @Redocly/dark-side

HCloward · 2024-05-21T16:07:43Z

docs/commands/completion.md

-From a bash prompt:
+### See bash shell example
+
+From a bash prompt, use the `completion` command:


Suggested change

From a bash prompt, use the `completion` command:

To generate an autocompletion script, run the following command from a bash or zsh prompt:

HCloward · 2024-05-21T16:08:21Z

docs/commands/completion.md


 ```bash
 redocly completion
 ```

-Outputs something like this:
+Outputs the following script:


Suggested change

Outputs the following script:

If run from a bash prompt, the `completion` command outputs the following autocompletion script:

HCloward · 2024-05-21T16:28:47Z

docs/commands/join.md

-{% /admonition %}
-
-### prefix-tags-with-info-prop
+### Use prefix-tags-with-info-prop option


Suggested change

### Use prefix-tags-with-info-prop option

### Prefix tags with specified `info` property

HCloward · 2024-05-21T16:29:26Z

docs/commands/join.md


-### prefix-tags-with-filename
+### Use prefix-tags-with-filename option


Suggested change

### Use prefix-tags-with-filename option

### Prefix tags with filename

HCloward · 2024-05-21T16:40:02Z

docs/commands/join.md


-### without-x-tag-groups
+### Use without-x-tag-groups option

 If you have the same tags in multiple API descriptions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.


Suggested change

If you have the same tags in multiple API descriptions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.

If you have the same tags in multiple API descriptions, you can avoid tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.

HCloward · 2024-05-21T16:40:16Z

docs/commands/join.md


-### without-x-tag-groups
+### Use without-x-tag-groups option


Suggested change

### Use without-x-tag-groups option

### Avoid tag duplication

HCloward · 2024-05-21T16:42:31Z

docs/commands/join.md


-### prefix-components-with-info-prop
+### Use prefix-components-with-info-prop option


Suggested change

### Use prefix-components-with-info-prop option

### Resolve conflicting component names

HCloward · 2024-05-21T16:43:12Z

docs/commands/join.md


-### Custom output file
+### Specify custom output file


Suggested change

### Specify custom output file

### Specify alternative filepath

HCloward · 2024-05-21T16:46:36Z

docs/commands/login.md


 ## Examples

-{% tabs %}
-{% tab label="Successful login" %}
+### See successful login


Suggested change

### See successful login

### View successful login message

HCloward · 2024-05-21T16:46:51Z

docs/commands/login.md


-{% /tab  %}
-{% tab label="Failed login" %}
+### See failed login


Suggested change

### See failed login

### View failed login message

HCloward · 2024-05-21T16:48:03Z

docs/commands/logout.md

@@ -21,7 +22,11 @@ redocly logout --version

 ## Examples

-```bash
+### See successful logout


Suggested change

### See successful logout

### View successful logout message

HCloward · 2024-05-21T16:50:32Z

docs/commands/preview-docs.md


-#### Pass api directly
+#### Pass API directly

 ```bash
 redocly preview-docs openapi/openapi.yaml
 ```

 In this case, `preview-docs` previews the API description that was passed to the command. The configuration file is ignored.


Suggested change

In this case, `preview-docs` previews the API description that was passed to the command. The configuration file is ignored.

In this case, `preview-docs` previews the API description that was passed to the command. Even if a configuration file exists, it is ignored.

HCloward · 2024-05-21T16:59:16Z

docs/commands/preview-docs.md


-### Custom configuration file
+### Use custom configuration file


Suggested change

### Use custom configuration file

### Use alternative filepath

adamaltman · 2024-05-21T19:44:48Z

docs/commands/join.md


-```bash
+<pre>


Why change from markdown syntax to html?

@adamaltman this is the purpose of the issue. We had a lot of either commands in text, or a wall of repeated code samples. The brief is to differentiate between the user's input, and displayed output examples.

HCloward · 2024-05-21T20:35:59Z

docs/commands/push.md


 Must be used only in combination with the `--batch-size` option.

-### Batch Size
+### Specify batch size


Suggested change

### Specify batch size

### Determine how many pushes are performed per batch

HCloward · 2024-05-21T20:36:40Z

docs/commands/push.md

@@ -279,7 +286,7 @@ redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=
 {% /tab  %}
 {% /tabs  %}

-### Public
+### Use public option


Suggested change

### Use public option

### Make API descriptions publicly accessible

HCloward · 2024-05-21T20:37:07Z

docs/commands/push.md

@@ -288,15 +295,15 @@ For more information on how to configure access to your APIs, check the [registr
 redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --public
 ```

-### Files
+### Use files option


Suggested change

### Use files option

### Upload other folders and files

HCloward · 2024-05-21T20:37:28Z

docs/commands/push.md


 The `--files` option allows you to upload other folders and files.

 ```bash
 redocly push openapi/petstore.yaml --destination=petstore-api@v1 --organization=openapi-org --files ./path/to/folder
 ```

-You can also add files and folders providing them in `redocly.yaml`:
+You can also add files and folders by providing them in `redocly.yaml` configuration file:


Suggested change

You can also add files and folders by providing them in `redocly.yaml` configuration file:

You can also add files and folders by providing them in the `redocly.yaml` configuration file:

HCloward · 2024-05-21T20:38:27Z

docs/commands/push.md

@@ -308,12 +315,12 @@ files:
  - ./file.md
 ```

-**`--files` has higher priority than `redocly.yaml`**
+Note that `--files` has higher priority than `redocly.yaml`.


Suggested change

Note that `--files` has higher priority than `redocly.yaml`.

Note that the `--files` option has higher priority than the `redocly.yaml` configuration file.

HCloward · 2024-05-21T20:47:10Z

docs/commands/split.md


-{% tabs %}
-{% tab label="Command" %}
+### See successful split


Suggested change

### See successful split

### View successful split message

HCloward · 2024-05-21T20:48:21Z

docs/commands/stats.md


 You can use the `stats` command with an OpenAPI description directly, with a command like the following:

 ```bash
 redocly stats openapi/openapi.yaml
 ```

-In this case, `stats` shows statistics for the API description that was passed to the command.
+In this case, `stats` shows statistics for the API description that was passed in. The configuration file is ignored.


Suggested change

In this case, `stats` shows statistics for the API description that was passed in. The configuration file is ignored.

In this case, `stats` shows statistics for the API description that was passed in. Even if the configuration file exists, it is ignored.

HCloward · 2024-05-21T20:49:27Z

docs/commands/stats.md


-### Custom configuration file
+### Use custom configuration file


Suggested change

### Use custom configuration file

### Use alternative filepath

HCloward · 2024-05-21T20:53:14Z

docs/commands/stats.md


 By default, the CLI tool looks for the [Redocly configuration file](../configuration/index.md) in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.

 ```bash
 redocly stats --config=./another/directory/config.yaml
 ```

-### Format
+### Specify output format

 #### Stylish (default)


Suggested change

#### Stylish (default)

#### Specify the stylish (default) output format

HCloward · 2024-05-21T20:53:34Z

docs/commands/stats.md


-You can use the JSON output to pass to another program.
+The JSON format output is suitable when you want to use the stats data in another program.

 #### Markdown


Suggested change

#### Markdown

#### Specify the Markdown output format

HCloward · 2024-05-21T20:53:53Z

docs/commands/stats.md


-In this format, `stats` shows the statistics in condensed but readable output with colored text and an icon at the beginning of each line.
+In this format, `stats` shows the statistics in a condensed but readable manner with an icon at the beginning of each line.

 #### JSON


Suggested change

#### JSON

#### Specify the JSON output format

HCloward

Hi @dianacheung - you have made some great updates with this PR. Thank you for your contribution. I made a few suggestions I would like you to take a look at. Thanks!

dianacheung · 2024-05-22T21:30:02Z

Hi @HCloward and @lornajane, thanks for reviewing and providing feedback. I'm out of office for rest of May and plan to pick this PR back up around mid June. I will reach out with any follow up questions on the feedback. Appreciate your patience.

dianacheung requested a review from a team as a code owner May 13, 2024 07:40

dianacheung mentioned this pull request May 13, 2024

Revisit Command pages #1429

Open

6 tasks

docs: updated commands documentation per issue 1429 and minor correct…

91f6fd4

…ions, ran prettier

dianacheung force-pushed the issue-1429 branch from a0d4725 to 91f6fd4 Compare May 13, 2024 08:23

HCloward reviewed May 21, 2024

View reviewed changes

adamaltman reviewed May 21, 2024

View reviewed changes

HCloward reviewed May 21, 2024

View reviewed changes

	The configuration file is ignored.
	Even if a configuration file exists, the command does not check for APIs listed in it.

	You can generate a build by giving the API alias name, as shown below:
	You can generate a build by including the API name with the command, as in the following example:

	Any additional configurations provided in the file are used by the command.
	Any additional configurations provided in the file are also used by the command.


		### Custom configuration file
		### Use custom configuration file

	### Use custom configuration file
	### Use alternative file path


		Build docs with hidden search box:
		The following command uses the optional `--theme.openapi` argument to build docs with hidden search box:


		Build docs using a custom Handlebars template and add custom `templateOptions`:
		The following command uses the optional `--templateOptions` argument to build docs using a custom Handlebars template and add a custom `templateOptions` object:

	The following command uses the optional `--templateOptions` argument to build docs using a custom Handlebars template and add a custom `templateOptions` object:
	The following command builds docs using a custom Handlebars template and adds metadata to the meta tag in the head of the page using `templateOptions`:

	### Use default configuration file
	### Use default location for configuration file

	### Use custom configuration file
	### Use alternative filepath

		@@ -14,13 +14,15 @@ The output is a script for you to copy and paste, and add to the configuration f

	From a bash prompt, use the `completion` command:
	To generate an autocompletion script, run the following command from a bash or zsh prompt:

	Outputs the following script:
	If run from a bash prompt, the `completion` command outputs the following autocompletion script:

	### Use prefix-tags-with-info-prop option
	### Prefix tags with specified `info` property


		### prefix-tags-with-filename
		### Use prefix-tags-with-filename option

	### Use prefix-tags-with-filename option
	### Prefix tags with filename

	If you have the same tags in multiple API descriptions, you can allow tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.
	If you have the same tags in multiple API descriptions, you can avoid tag duplication by using the `without-x-tag-groups` option. In this case, the `x-tagGroups` property is not created in the joined file.

	### Use without-x-tag-groups option
	### Avoid tag duplication


		### prefix-components-with-info-prop
		### Use prefix-components-with-info-prop option

	### Use prefix-components-with-info-prop option
	### Resolve conflicting component names

docs: updated commands documentation (issue 1429) and minor corrections. #1560

Are you sure you want to change the base?

docs: updated commands documentation (issue 1429) and minor corrections. #1560

Conversation

dianacheung commented May 13, 2024

What/Why/How?

Reference

Testing

changeset-bot bot commented May 13, 2024 • edited

⚠️ No Changeset found

dianacheung commented May 13, 2024

dianacheung commented May 19, 2024

lornajane commented May 20, 2024

HCloward May 21, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HCloward May 21, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HCloward May 21, 2024 • edited

Choose a reason for hiding this comment

HCloward May 21, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HCloward May 21, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

HCloward left a comment

Choose a reason for hiding this comment

dianacheung commented May 22, 2024

changeset-bot bot commented May 13, 2024 •

edited

HCloward May 21, 2024 •

edited

HCloward May 21, 2024 •

edited

HCloward May 21, 2024 •

edited

HCloward May 21, 2024 •

edited

HCloward May 21, 2024 •

edited

	### Specify custom output file
	### Specify alternative filepath

	In this case, `preview-docs` previews the API description that was passed to the command. The configuration file is ignored.
	In this case, `preview-docs` previews the API description that was passed to the command. Even if a configuration file exists, it is ignored.

	### Specify batch size
	### Determine how many pushes are performed per batch

	### Use public option
	### Make API descriptions publicly accessible

	You can also add files and folders by providing them in `redocly.yaml` configuration file:
	You can also add files and folders by providing them in the `redocly.yaml` configuration file:

	Note that `--files` has higher priority than `redocly.yaml`.
	Note that the `--files` option has higher priority than the `redocly.yaml` configuration file.

	In this case, `stats` shows statistics for the API description that was passed in. The configuration file is ignored.
	In this case, `stats` shows statistics for the API description that was passed in. Even if the configuration file exists, it is ignored.

	#### Stylish (default)
	#### Specify the stylish (default) output format