Document the difference between `redoc`, `redoc-cli`, and `@redocly/cli` packages

[jasonbarry]

I'm a new user reading the documentation for the first time. I don't understand the relationship between

• redoc
• redoc-cli
• @redocly-cli

Are some of these deprecated? redoc says it can "Generate interactive API documentation from OpenAPI definitions", but so can npx @redocly/cli build-docs. However, I don't see any build-docs command on this page: https://redocly.com/docs/cli/commands/

Which should I use to generate html documentation from openapi spec?

[adamaltman]

@jasonbarry we withheld the docs because we are expecting a configuration option to change and want to support a unified configuration file across our entire product suite.

I believe we'll get to this change early in the new year and we will publish the corresponding docs for the command at that time.

https://github.com/Redocly/redocly-cli/pull/892/files#r1059515200

• redoc is an OpenAPI renderer, and the "build-docs" command is one deployment mechanism (it generates html/css/js). There are other deployment mechanisms such as the HTML element: https://redocly.com/docs/redoc/deployment/html/
• redoc-cli is going to be deprecated in favor of @redocly/cli build-docs command (the CLI has other commands documented).
• @redocly/cli is going to be a single CLI tool with multiple commands related to APIs such as linting, bundling, previewing, and building docs.

[jasonbarry]

Makes sense @adamaltman, thanks for the response! Feel free to close this issue out if you'd like.

[adamaltman]

We'll close it once we ship the docs. Thanks.