Docs: fully revised preview-docs command for openapi-cli

docs/commands/preview-docs.md

@@ -1,39 +1,100 @@
 # `preview-docs`
 
-Preview the API reference docs on your local machine.
+## Introduction
 
-If you have a license key, you will have a preview of the premium Redocly API reference docs. The [`login`](./login.md) command also generates a preview of the premium Redocly API reference docs.
+With this command, you can generate documentation previews for API definitions on your local machine.
 
-Otherwise, you'll get a preview of Redoc community edition.
+If you have a license key or API key, you will get a preview of the premium [Redocly API reference docs](https://redoc.ly/reference-docs). If you don't, you will get a preview of [Redoc community edition](https://redoc.ly/redoc).
 
+:::success Tip
+To preview docs using the premium Redocly API reference docs, you must first authenticate to the API registry with the [`login`](./login.md) command.
+:::
 
-### `preview-docs` usage
+## Usage
 
+```bash
+openapi preview-docs <entrypoint> [branchName]
+openapi preview-docs <entrypoint> [--config=<path>] [--port=<value>] [branchName]
+openapi preview-docs <entrypoint> [--force] [--help] [--version] [branchName]
+openapi preview-docs <entrypoint> --version
+```
+
+## Options
+
+Option                    | Type      | Required     | Default     | Description
+--------------------------|:---------:|:------------:|:-----------:|------------
+`entrypoint`              | `string`  | yes          | -           | Path to the API definition filename or configuration alias that you want to generate preview for. Refer to [the entrypoints section](#entrypoints) for more options.
+`--config`                | `string`  | no           | -           | Specify path to the [config file](#custom-configuration-file)
+`--force`, `-f`           | `boolean` | no           | -           | Generate preview output even when errors occur
+`--help`                  | `boolean` | no           | -           | Show help
+`--port`, `-p`            | `number`  | no           | 8080        | Specify the port where the documentation preview can be accessed. You can set any port as long as it is not used by applications in your operating system.
+`--skip-decorator`        | `array`   | no           | -           | Ignore [certain decorators](#skip-preprocessor-or-decorator)
+`--skip-preprocessor`     | `array`   | no           | -           | Ignore [certain preprocessors](#skip-preprocessor-or-decorator)
+`--use-community-edition` | `boolean` | no           | -           | Force using Redoc Community Edition for docs preview
+`--version`               | `boolean` | no           | -           | Show version number
+
+## Examples
 
-```shell
-Positionals:
-  entrypoint                                                 [string] [required]
+### Entrypoints
 
-Options:
-  --version                Show version number.                        [boolean]
-  --help                   Show help.                                  [boolean]
-  --port, -p               Preview port.                [number] [default: 8080]
-  --skip-preprocessor      Ignore certain preprocessors.                 [array]
-  --skip-decorator         Ignore certain decorators.                    [array]
-  --use-community-edition  Force using Redoc CE for docs preview.      [boolean]
-  --force, -f              Produce bundle output even when errors occur.
-                                                                       [boolean]
-  --config                 Specify path to the config file.             [string]
+The command behaves differently depending on how you pass a path to the entrypoint to it and whether the [configuration file](#custom-configuration-file) exists.
+
+#### Pass entrypoint directly
+
+```bash
+openapi preview-docs openapi/openapi.yaml
 ```
 
+In this case, `preview-docs` will preview the definition that was passed to the command. The configuration file is ignored.
 
-### How to preview the docs on a custom port
+#### Pass entrypoint alias
 
-By default, without providing a port, the preview starts on port 8080, and can be accessed at `http://localhost:8080`.
+Instead of a full path, you can use an alias assigned in the `apiDefinitions` section within your `.redocly.yaml` configuration file as the entrypoint. For example, `petstore`:
 
-This command starts a preview on port 8888, and you can access the docs at `http://localhost:8888` after running it.
+```bash command
+openapi preview-docs petstore
+```
 
+```yaml .redocly.yaml
+apiDefinitions:
+  petstore: ./openapi/petstore-definition.json
+```
+
+In this case, after resolving the path behind the `petstore` alias (example in the `.redocly.yaml` tab), `preview-docs` will preview the `petstore.json` definition file. For this approach, the `.redocly.yaml` configuration file is mandatory.
+
+### Custom configuration file
+
+By default, the CLI tool looks for a `.redocly.yaml` configuration file in the current working directory. Use the optional `--config` argument to provide an alternative path to a configuration file.
+
+```bash
+openapi preview-docs --config=./another/directory/config.yaml
+```
 
-```shell
+### Custom port for preview
+
+By default, without using the `port` option, the preview starts on port `8080`, so you can access the docs at `http://localhost:8080`
+
+To specify a custom port for the preview, pass the desired value using either short or long option format:
+
+```bash short format
 openapi preview-docs -p 8888 openapi/openapi.yaml
 ```
+
+```bash long format
+openapi preview-docs -port 8888 openapi/openapi.yaml
+```
+
+Both commands will start the preview on port `8888`, so you can access the docs at `http://localhost:8888`
+
+
+### Skip preprocessor or decorator
+
+You may want to skip specific preprocessors, rules, or decorators upon running the command.
+
+```bash Skip preprocessors
+openapi preview-docs --skip-preprocessor=discriminator-mapping-to-one-of,another-example
+```
+
+```bash Skip decorators
+openapi preview-docs --skip-decorator=generate-code-samples,remove-internal-operations
+```