From 90f8e46733c4cace8eba1c2c1f7df291a2bd6926 Mon Sep 17 00:00:00 2001 From: Danny Sheridan <83524670+dannysheridan@users.noreply.github.com> Date: Sat, 25 Jan 2025 18:28:36 -0500 Subject: [PATCH] chore(docs): Enhance CLI command reference (#5757) * changes * chore(docs): rewrite Fern CLI commands for clarity & include generate --preview * update spacing * consolidate * add clarity and formatting * enhance with quick reference * add a fern cli quickstart and reduce content on commands page --------- Co-authored-by: fern-bot --- fern/docs.yml | 50 +++--- fern/pages/cli-api/commands.mdx | 232 +++++++++++++++----------- fern/pages/cli-api/get-started.mdx | 83 +++++++++ fern/pages/cli-api/global-options.mdx | 60 ++++++- fern/pages/cli-api/overview.mdx | 42 ----- 5 files changed, 295 insertions(+), 172 deletions(-) create mode 100644 fern/pages/cli-api/get-started.mdx delete mode 100644 fern/pages/cli-api/overview.mdx diff --git a/fern/docs.yml b/fern/docs.yml index 7984b26d32c..796989c3366 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -38,28 +38,6 @@ tabs: css: ./assets/styles.css -redirects: - - source: /learn/api-definition/fern/api-yml-reference - destination: /learn/api-definition/fern/api-yml/overview - - source: /learn/docs/api-references/api-playground/:slug - destination: /learn/docs/api-references/api-explorer/:slug - - source: /learn/docs/api-references/api-playground - destination: /learn/docs/api-references/api-explorer - - source: /learn/sdks/features/:slug - destination: /learn/sdks/capabilities/:slug - - source: /learn/sdks/package-managers/:slug - destination: /learn/sdks/guides/publish-to-package-managers/:slug - - source: /learn/sdks/introduction/configuration - destination: /learn/sdks/introduction/language-support - - source: /learn/sdks/getting-started/generate-your-first-sdk - destination: /learn/sdks/guides/generate-your-first-sdk - - source: /learn/sdks/getting-started/preview-your-sdk-locally - destination: /learn/sdks/guides/preview-your-sdk-locally - - source: /learn/sdks/getting-started/publish-a-public-facing-sdk - destination: /learn/sdks/guides/publish-a-public-facing-sdk - - source: /learn/docs/building-your-docs/:slug - destination: /learn/docs/building-and-customizing-your-docs/:slug - navigation: - tab: home layout: @@ -583,8 +561,8 @@ navigation: layout: - section: CLI Reference contents: - - page: CLI Overview - path: ./pages/cli-api/overview.mdx + - page: Get Started with Fern CLI + path: ./pages/cli-api/get-started.mdx - page: Global Options path: ./pages/cli-api/global-options.mdx - page: Commands @@ -654,3 +632,27 @@ analytics: api-key: ${POSTHOG_API_KEY} gtm: container-id: GTM-55W3VNDW + +redirects: + - source: /learn/api-definition/fern/api-yml-reference + destination: /learn/api-definition/fern/api-yml/overview + - source: /learn/docs/api-references/api-playground/:slug + destination: /learn/docs/api-references/api-explorer/:slug + - source: /learn/docs/api-references/api-playground + destination: /learn/docs/api-references/api-explorer + - source: /learn/sdks/features/:slug + destination: /learn/sdks/capabilities/:slug + - source: /learn/sdks/package-managers/:slug + destination: /learn/sdks/guides/publish-to-package-managers/:slug + - source: /learn/sdks/introduction/configuration + destination: /learn/sdks/introduction/language-support + - source: /learn/sdks/getting-started/generate-your-first-sdk + destination: /learn/sdks/guides/generate-your-first-sdk + - source: /learn/sdks/getting-started/preview-your-sdk-locally + destination: /learn/sdks/guides/preview-your-sdk-locally + - source: /learn/sdks/getting-started/publish-a-public-facing-sdk + destination: /learn/sdks/guides/publish-a-public-facing-sdk + - source: /learn/docs/building-your-docs/:slug + destination: /learn/docs/building-and-customizing-your-docs/:slug + - source: /learn/cli-api/cli-reference/cli-overview + destination: /learn/cli-api/cli-reference/get-started \ No newline at end of file diff --git a/fern/pages/cli-api/commands.mdx b/fern/pages/cli-api/commands.mdx index 79b96b905b1..c9c91496cb1 100644 --- a/fern/pages/cli-api/commands.mdx +++ b/fern/pages/cli-api/commands.mdx @@ -1,11 +1,82 @@ --- title: 'Commands' -description: 'Fern CLI command documentation' +description: 'Complete reference for all Fern CLI commands for generating SDKs and developer documentation.' +subtitle: 'Learn about the Fern CLI commands.' --- -Explore documentation for popular Fern CLI commands. +| Command | Description | +|---------|-------------| +| [`fern init`](#fern-init) | Initialize new Fern API projects | +| [`fern check`](#fern-check) | Validate API definition & configuration for development and CI | +| [`fern upgrade`](#fern-upgrade) | Update Fern CLI & compiler to latest versions | + +## Documentation Commands +| Command | Description | +|---------|-------------| +| [`fern docs dev`](#fern-docs-dev) | Run local documentation preview server | +| [`fern generate --docs`](#fern-generate---docs) | Build & publish documentation updates | +| [`fern docs broken-links`](#fern-docs-broken-links) | Validate documentation links for quality assurance | + +## SDK Generation Commands +| Command | Description | +|---------|-------------| +| [`fern generate`](#fern-generate) | Build & publish SDK updates | +| [`fern write-definition`](#fern-write-definition) | Convert OpenAPI specifications to [Fern Definition](/learn/overview) | +| [`fern write-overrides`](#fern-write-overrides) | Create OpenAPI customizations and enhancements | +| [`fern generator upgrade`](#fern-generator-upgrade) | Update SDK generators to latest versions | + +## Detailed Command Documentation + + + + Use `fern generate` to run the Fern compiler and create SDKs for your API. + + + ```bash + fern generate [--group ] [--api ] [--version ] [--preview] + ``` + + + ### preview + + Use `--preview` to test SDK changes locally before publishing. This is especially useful during development: + - Generates SDK into a local `.preview/` folder + - Allows quick iteration on your Fern definition + - No changes are published to package managers or GitHub + + ```bash + # Preview all SDKs + fern generate --preview + + # Preview specific SDK group + fern generate --group python-sdk --preview + ``` + + ### group + + Use `--group ` to filter to a specific group within `generators.yml`. Required unless you have a `default-group` declared. + + ```bash + fern generate --group internal + ``` + + ### api + + Use `--api ` to specify the API for SDK generation. + + ```bash + fern generate --api public-api + ``` + + ### version + + Use `--version` to specify a version for SDKs and documentation. Adherence to [semantic versioning](https://semver.org/) is advised. + + ```bash + fern generate --version 2.11 + ``` - + @@ -51,22 +122,23 @@ Explore documentation for popular Fern CLI commands. name: Fern Validation Check on: - pull_request: - branches: - main + pull_request: + push: + branches: + - main jobs: - validate-fern-api: - name: Validate using Fern's linter - runs-on: ubuntu-latest - + validate-fern-api: + name: Validate using Fern's linter + runs-on: ubuntu-latest steps: - - name: Checkout repository + - name: Checkout repository uses: actions/checkout@v4 - - name: Install Fern + - name: Install Fern CLI run: npm install -g fern-api - - name: Validate API with Fern + - name: Validate API with Fern run: fern check ``` @@ -74,74 +146,6 @@ Explore documentation for popular Fern CLI commands. - - - - - Use `fern generate` to run the Fern compiler and create SDKs for your API. - - - ```bash - fern generate [--group ] [--api ] [--version ] [--local] [--keepDocker] [--preview] - ``` - - - ### group - - Use `--group ` to filter to a specific group within `generators.yml`. Required unless you have a `default-group` declared in `generators.yml`. - - ```bash - fern generate --group internal - ``` - - ### api - - Use `--api ` to specify the API for SDK generation. - - ```bash - fern generate --api public-api - ``` - - ### version - - Use `--version` to specify a version for SDKs and documentation. Adherance to [semantic versioning](https://semver.org/) is advised. - - ```bash - fern generate --version 2.11 - ``` - - ### preview - - Use `--preview` to preview updates to your SDKs before pushing changes to your GitHub repo or publishing to a package manager. The preview SDK will be generated into the `.preview/` folder. - - ```bash - fern generate --preview - ``` - - ### local - - Use `--local` to generate code locally by downloading the Docker Image and running it on your machine. - Note that running Docker locally supports outputting files, and not publishing to package managers. - - ```bash - fern generate --local - ``` - - [Docker Desktop](https://www.docker.com/products/docker-desktop/) must be installed and running on your machine. - - ### keepDocker - - Use `--keepDocker` to keep the Docker container running after the generation is complete. This is useful for debugging. - - ```bash - fern generate --local --keepDocker - ``` - - [Docker Desktop](https://www.docker.com/products/docker-desktop/) must be installed and running on your machine. - - - - Use `fern generate --docs` to create a documentation site for your API. @@ -170,7 +174,6 @@ Explore documentation for popular Fern CLI commands. - Use `fern docs dev` to run a local development server to preview your docs. @@ -191,7 +194,6 @@ Explore documentation for popular Fern CLI commands. - Use `fern docs broken-links` to check for broken links in your API docs. @@ -213,7 +215,6 @@ Explore documentation for popular Fern CLI commands. - Use `fern upgrade` will upgrade your compiler version in `fern.config.json` to the @@ -221,24 +222,15 @@ Explore documentation for popular Fern CLI commands. ```bash - fern upgrade [--rc] + fern upgrade ``` - ### rc - - Use `--rc` to upgrade to the compiler's latest release candidate. Using a release candidate is not recommended for production use. - - ```bash - fern upgrade --rc - ``` - - - Use `fern init` to initialize a new Fern workspace in the current folder. By default, you’ll see the IMDb API example. + Use `fern init` to initialize a new Fern workspace in the current folder. By default, you'll see the IMDb API example. ```bash @@ -319,7 +311,6 @@ Explore documentation for popular Fern CLI commands. - Use `fern login` to login to the Fern CLI via GitHub. Logging in allows you @@ -345,7 +336,6 @@ Explore documentation for popular Fern CLI commands. - Use `fern token `to generate a `FERN_TOKEN` specific to your organization defined @@ -354,7 +344,7 @@ Explore documentation for popular Fern CLI commands. ```bash fern token - ``` + ``` ## GitHub Actions @@ -373,7 +363,6 @@ Explore documentation for popular Fern CLI commands. - Use `fern write-definition` to convert your OpenAPI Specification into a Fern Definition. @@ -397,7 +386,7 @@ Explore documentation for popular Fern CLI commands. └─ api.yml └─ __package__.yml ``` - + If you do not see the `.definition/` folder, use the appropriate command or configuration to view hidden folders (`ls -a` in `bash` and `zsh`). @@ -415,7 +404,6 @@ Explore documentation for popular Fern CLI commands. ``` - Use `fern write-overrides` to generate a basic OpenAPI overrides file. An overrides file allows for @@ -456,4 +444,48 @@ Explore documentation for popular Fern CLI commands. ``` + + + Use `fern generator upgrade` to update all generators in your `generators.yml` to their latest versions. + + + ```bash + fern generator upgrade [--list] [--generator ] [--group ] + ``` + + + This command will: + - Check for updates to all generators specified in your `generators.yml` + - Update the generator versions to their latest compatible releases + - Maintain compatibility with your current Fern compiler version + + ### list + + Use `--list` to see all available generator upgrades without applying them. + + ```bash + fern generator upgrade --list + ``` + + ### generator + + Use `--generator` to specify a particular generator type to upgrade. + + ```bash + fern generator upgrade --generator fernapi/fern-typescript-node-sdk + fern generator upgrade --generator fernapi/fern-python-sdk + ``` + + ### group + + Use `--group` to upgrade generators within a specific group in your `generators.yml`. If not specified, all generators of the specified type will be upgraded. + + ```bash + fern generator upgrade --group public + ``` + + + This is different from `fern upgrade` which updates the Fern CLI version. Use both commands to keep your entire Fern toolchain up to date. + + \ No newline at end of file diff --git a/fern/pages/cli-api/get-started.mdx b/fern/pages/cli-api/get-started.mdx new file mode 100644 index 00000000000..329a0797456 --- /dev/null +++ b/fern/pages/cli-api/get-started.mdx @@ -0,0 +1,83 @@ +--- +title: 'Overview' +subtitle: Manage and configure your Fern projects, all from the command line. +description: 'Overview of the Fern CLI including usage, installation, and CI/CD environments' +--- + +## Installing Fern CLI + +Run the following command to download and install Fern CLI from the [npm](https://www.npmjs.com/) registry. + +```bash +npm install -g fern-api # install Fern CLI +fern -v # ensure Fern was successfully installed +``` + +## CLI Quick Start + +Get started with these commonly used commands: + + +```bash +# Docs Development +fern init --docs # Create a new documentation project +fern docs dev # Preview docs locally at localhost:3000 +fern generate --docs --preview # Preview documentation changes +fern generate --docs # Generate and publish documentation + +# SDK Development +fern init # Start new SDK project +fern check # Validate API definition +fern generate --preview # Preview SDKs in .preview/ folder +fern generate # Generate default SDK group +fern generate --group ts-sdk # Generate specific SDK group +``` + + + +The "default SDK group" refers to the group marked as default in your `generators.yml`. Learn more about [default groups](/learn/generate-sdks/configuration#default-group). + + +## Common Workflows + + + + 1. Initialize a new docs project: + ```bash + fern init --docs + ``` + + 2. Preview locally while making changes: + ```bash + fern docs dev + ``` + + 3. When ready to preview or publish: + ```bash + fern generate --docs --preview # Generate a shareable preview link + fern generate --docs # Publish to production + ``` + + + + 1. Initialize a new SDK project: + ```bash + fern init + ``` + + 2. Configure your generators in [`generators.yml`](/learn/generate-sdks/configuration) + + 3. Generate SDKs: + ```bash + fern generate --preview # Preview changes locally + fern generate --group python-sdk --preview # Preview specific SDK group + fern generate # Publish to production + ``` + + + During development, use `--preview` to test your changes locally before publishing. + The preview SDK will be generated into the `.preview/` folder. + + + + \ No newline at end of file diff --git a/fern/pages/cli-api/global-options.mdx b/fern/pages/cli-api/global-options.mdx index 95527645ca3..15be225ff29 100644 --- a/fern/pages/cli-api/global-options.mdx +++ b/fern/pages/cli-api/global-options.mdx @@ -1,9 +1,26 @@ --- title: 'Global options' description: 'Global options for the Fern CLI' +subtitle: 'Explore Fern CLI global options.' --- -Global options are available to use with many Fern CLI commands. Read more below. +## Quick Reference + +| Option | Description | Example | +|--------|-------------|---------| +| [`--help`](#help) | Show command help and options | `fern --help` | +| [`--log-level`](#log-level) | Set logging verbosity | `fern generate --log-level debug` | +| [`--api`](#api) | Target specific API | `fern generate --api public-api` | +| [`--group`](#group) | Target specific generator group | `fern generate --group php-sdk` | +| [`--version`](#version) | Specify the SDK version number | `fern generate --version 1.2.3` | + + +When troubleshooting: +- Use `--log-level debug` to see detailed output when encountering issues +- When using `--api`, ensure the API name matches exactly with the directory name in your `fern/apis/` folder + + +The following sections describe each global option in detail. ## help @@ -41,13 +58,44 @@ Options: ## log-level -Use the `--log-level` option to see more information about Fern's actions. +Use the `--log-level` option to set the verbosity of Fern's logging output. The default level is `info`. -- debug: Debug messages, informational messages, warnings, and errors are logged. -- **info [default]**: Informational messages, warnings, and errors are logged. -- warn: Warnings and errors are logged. -- error: Only error messages are logged. +Available levels (from most to least verbose): +- `debug`: Debug messages, informational messages, warnings, and errors +- `info`: Informational messages, warnings, and errors +- `warn`: Warnings and errors only +- `error`: Error messages only ```bash fern generate --log-level debug ``` + +## api + +Use the `--api` option to target a specific API. This is particularly useful when your project contains multiple API definitions. The API name should match the directory name in your `fern/apis/` folder. + +```bash +# Generate SDKs for only the "payments-api" +fern generate --api payments-api +``` + +## group + +Use the `--group` option to target a specific generator group. + +```bash +# Generate only the Ruby SDK group +fern generate --group ruby-sdk +``` + +## version + +Use the `--version` option to specify the SDK version number, typically following semantic versioning (semver) format (`MAJOR.MINOR.PATCH`). This is particularly useful in CI/CD pipelines when publishing SDK releases. + +```bash +# Generate Python SDK the payments API with version 1.2.3 +fern generate --api payments-api --group python-sdk --version 1.2.3 + +# Generate TypeScript SDK for the auth API with version 0.1.0 +fern generate --api auth --group ts-sdk --version 0.1.0 +``` \ No newline at end of file diff --git a/fern/pages/cli-api/overview.mdx b/fern/pages/cli-api/overview.mdx deleted file mode 100644 index f60a01c16dd..00000000000 --- a/fern/pages/cli-api/overview.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: 'Overview' -subtitle: Manage and configure your Fern projects, all from the command line. -description: 'Overview of the Fern CLI including usage, installation, and CI/CD environments' ---- - -Use the Fern CLI to manage and test your documentation, SDKs, permissions, and API specification from the terminal or via an automated system. - -Check out the [API Reference](/learn/cli-api/api-reference/overview) to interact with Fern programmatically. - -## Installing Fern CLI - -Run the following command to download and install Fern CLI from the [npm](https://www.npmjs.com/) registry. - -```bash -npm install -g fern-api -``` - -## Updating Fern CLI - -When there is a newer version of Fern CLI available, running any command will trigger an alert. To update Fern, run the same installation command yet again. - -```bash -npm install -g fern-api@latest -``` - - -Run `fern upgrade` to update the Fern CLI *and* your project's generators. - - -## Checking the version - -Use `--version`, shorthand `-v`, to check the Fern CLI version currently being used. - -```bash -fern -v -0.26.10 -``` - -## Authentication and CI/CD - -Fern CLI requires authentication before accessing an organization’s resources. To authenticate manually, login using GitHub using `fern login`. To enable Fern CLI use in CI/CD environments, and for an example showing how to set up Fern and GitHub Actions, check out [`fern token`](/learn/cli-api/cli-reference/commands#fern-token).