From 332ea66bacd425aba671ae7d8f4c7d03f0210e20 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 15 Feb 2022 16:45:15 -0600 Subject: [PATCH 01/43] docs: add GitHub Actions guidance --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index cb10c2b8e..8cd03760a 100644 --- a/README.md +++ b/README.md @@ -4,19 +4,33 @@ [![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) -`rdme` is the CLI wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to upload and edit [OpenAPI](https://swagger.io/specification/) and [Swagger](https://swagger.io/specification/v2/) files associated with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. +`rdme` is the CLI and [GitHub Action](https://docs.github.com/actions) wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to sync [OpenAPI](https://spec.openapis.org) and [Swagger](https://swagger.io/specification/v2/) files with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. ## Configuration -### Installation +### Setup + +> These setup instructions are for CLI usage only. For usage in GitHub Actions, see [GitHub Actions](#github-actions) below. + +We recommend installing `rdme` in your project's `devDependencies` so you don't run into unexpected behavior with mismatching versions: + +```sh +npm install rdme --save-dev +``` + +Once installed, we recommend using `npx` (which is included if you have `npm` installed) to prefix all of your CLI commands. For example: ```sh -npm install rdme +npx rdme validate [file] ``` +To ensure you're getting the latest features and security updates, we recommend using a tool like [Dependabot](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates) to keep `rdme` (and your other dependencies) up-to-date. + ### Authentication -If you authenticate `rdme` to your ReadMe project, we will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`) so you will not have to provide the `--key` option to commands that require it. +For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing your project API key via the `--key` option instead of the configuration file authentication described below. + +For local CLI usage with a single project, you can authenticate `rdme` to your ReadMe project. This will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`) so you will not have to provide the `--key` option to commands that require it. ```sh rdme login @@ -33,6 +47,37 @@ If you wish to get more information about any command within `rdme`, you can exe - `--key `: The API key associated with your ReadMe project. You can obtain this from your dashboard, or alternatively if you log in with `rdme login`, we will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`), saving you the hassle of having to supply this argument on commands that have it. - `--version `: Your project version. +### GitHub Actions + + + +> For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/automatically-sync-api-specification-with-github). + +For usage in GitHub Actions, create [a new GitHub Workflow file](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: + +```yml +- uses: actions/checkout@v2 +- uses: readmeio/rdme@XX + with: + rdme: [your command here] +``` + +The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command: + +```sh +rdme openapi path/to/openapi.json --key=API_KEY --id=OPENAPI_ID +``` + +To execute this command via GitHub Actions, the step would look like this: + +```yml +- uses: readmeio/rdme@XX + with: + rdme: openapi path/to/openapi.json --key=API_KEY --id=OPENAPI_ID +``` + +Note that the `@XX` in the above examples refers to the version of `rdme` (e.g. `@7.0`). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). + ### OpenAPI / Swagger ReadMe supports [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), and [Swagger 2.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md). From 329312f10fb4077869905167b66bc1b19cea4d08 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 16 Feb 2022 05:16:02 -0600 Subject: [PATCH 02/43] Update README.md Co-authored-by: Jon Ursenbach --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8cd03760a..a3a07408d 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) -`rdme` is the CLI and [GitHub Action](https://docs.github.com/actions) wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to sync [OpenAPI](https://spec.openapis.org) and [Swagger](https://swagger.io/specification/v2/) files with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. +`rdme` is the CLI and [GitHub Action](https://docs.github.com/actions) wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to sync [OpenAPI](https://spec.openapis.org) and [Swagger](https://swagger.io/specification/v2/) definitions with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. ## Configuration From ced4541f3be47711b25370bdc300aa0cd71d95fb Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 16 Feb 2022 09:43:56 -0600 Subject: [PATCH 03/43] chore: PR feedback Co-Authored-By: Ryan Park --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a3a07408d..b31091fb8 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ > These setup instructions are for CLI usage only. For usage in GitHub Actions, see [GitHub Actions](#github-actions) below. -We recommend installing `rdme` in your project's `devDependencies` so you don't run into unexpected behavior with mismatching versions: +We recommend installing `rdme` in your project rather than doing a global installation so you don't run into unexpected behavior with mismatching versions. We also suggest using the `--save-dev` flag since `rdme` is typically used as part of a CI process and is unlikely to be running in your production application: ```sh npm install rdme --save-dev From 6089539d7c2b52dcd91184f80cca2f33f37177ee Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 16 Feb 2022 10:01:52 -0600 Subject: [PATCH 04/43] chore: more docs cleanup --- README.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b31091fb8..b9639f7bf 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ To ensure you're getting the latest features and security updates, we recommend ### Authentication -For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing your project API key via the `--key` option instead of the configuration file authentication described below. +For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing your project API key via the `--key` option (instead of the configuration file authentication described below). For local CLI usage with a single project, you can authenticate `rdme` to your ReadMe project. This will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`) so you will not have to provide the `--key` option to commands that require it. @@ -44,8 +44,8 @@ If you wish to get more information about any command within `rdme`, you can exe ### Common `rdme` Options -- `--key `: The API key associated with your ReadMe project. You can obtain this from your dashboard, or alternatively if you log in with `rdme login`, we will save your API key to a local configuration file (`~/.config/configstore/rdme-production.json`), saving you the hassle of having to supply this argument on commands that have it. -- `--version `: Your project version. +- `--key `: 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. +- `--version `: Your project version. See [our docs](https://docs.readme.com/docs/versions) for more information. ### GitHub Actions @@ -80,7 +80,7 @@ Note that the `@XX` in the above examples refers to the version of `rdme` (e.g. ### OpenAPI / Swagger -ReadMe supports [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), and [Swagger 2.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md). +ReadMe supports [OpenAPI 3.1](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md), [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md), and [Swagger 2.x](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md). The following examples use JSON files, but we support API Definitions that are written in either JSON or YAML. @@ -104,16 +104,12 @@ rdme openapi [path-to-file.json] --id={existing-id} #### Uploading or Editing an API Definition in a Project Version -You can additional include a version flag, specifying the target version for your file's destination +You can additional include a version flag, specifying the target version for your file's destination. This approach will provide you with CLI prompts, so we do not recommend this technique in CI environments. ```sh rdme openapi [path-to-file.json] --version={project-version} ``` -```sh -rdme openapi [path-to-file.json] --id={existing-id} --version={project-version} -``` - #### Omitting the File Path If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. We will then look for a file with the following names, and upload that: `openapi.json`, `openapi.yaml`, `swagger.json`, and `swagger.yaml`. From 3da17d950396e7825c26a6901dbe83aa52254ad6 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 16 Feb 2022 12:09:59 -0600 Subject: [PATCH 05/43] chore: cleanup rearrange some links, remove language from GitHub docs URLs --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index b9639f7bf..4839849dc 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) -`rdme` is the CLI and [GitHub Action](https://docs.github.com/actions) wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to sync [OpenAPI](https://spec.openapis.org) and [Swagger](https://swagger.io/specification/v2/) definitions with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. +`rdme` is the CLI and [GitHub Action](#github-actions) wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to sync [OpenAPI](https://spec.openapis.org) and [Swagger](https://swagger.io/specification/v2/) definitions with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. ## Configuration @@ -24,7 +24,7 @@ Once installed, we recommend using `npx` (which is included if you have `npm` in npx rdme validate [file] ``` -To ensure you're getting the latest features and security updates, we recommend using a tool like [Dependabot](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates) to keep `rdme` (and your other dependencies) up-to-date. +To ensure you're getting the latest features and security updates, we recommend using a tool like [Dependabot](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates) to keep `rdme` (and your other dependencies) up-to-date. ### Authentication @@ -53,7 +53,7 @@ If you wish to get more information about any command within `rdme`, you can exe > For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/automatically-sync-api-specification-with-github). -For usage in GitHub Actions, create [a new GitHub Workflow file](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: +For usage in [GitHub Actions](https://docs.github.com/actions), create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: ```yml - uses: actions/checkout@v2 @@ -76,7 +76,7 @@ To execute this command via GitHub Actions, the step would look like this: rdme: openapi path/to/openapi.json --key=API_KEY --id=OPENAPI_ID ``` -Note that the `@XX` in the above examples refers to the version of `rdme` (e.g. `@7.0`). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). +Note that the `@XX` in the above examples refers to the version of `rdme` (e.g. `@7.0`). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). ### OpenAPI / Swagger From 44472155c0ca9dba22936b5656012f38de476c82 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 22 Feb 2022 15:56:20 -0600 Subject: [PATCH 06/43] ci: add workflow for syncing docs to ReadMe! --- .github/workflows/docs.yml | 24 ++++++++++++++++++++++++ documentation/rdme.md | 7 +++++++ 2 files changed, 31 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 documentation/rdme.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..3355c0f72 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,24 @@ +name: Sync `documentation` directory to ReadMe + +# Run workflow for every push to the `main` branch +on: + push: + branches: + - main + +jobs: + sync: + runs-on: ubuntu-latest + steps: + - name: Checkout this repo + uses: actions/checkout@v2.4.0 + + # Run GitHub Action to sync docs in `documentation` directory + - name: GitHub Action + # Use the `main` branch as ref for GitHub Action + # Not recommended, this can break your workflows! + # We recommend specifying a fixed version + # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions + uses: readmeio/rdme@main + with: + rdme: docs ./documentation --key=${{ secrets.README_PROD_PROJECT_API_KEY }} --version=2.0 diff --git a/documentation/rdme.md b/documentation/rdme.md new file mode 100644 index 000000000..2ad1d8640 --- /dev/null +++ b/documentation/rdme.md @@ -0,0 +1,7 @@ +--- +title: rdme +category: 5f7ce9e3a5504d0414d024c2 +hidden: true +--- + +Hello Owlbert! From c21cebd5cae4ec878cd3373ee93372830c52d8e4 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 22 Feb 2022 16:00:00 -0600 Subject: [PATCH 07/43] chore: temporarily run workflow on every push We're going to revert this, but just want to confirm that our changes work! Co-Authored-By: Ellie Rossuck <48635728+ellierossuck@users.noreply.github.com> --- .github/workflows/docs.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3355c0f72..ab6bfc680 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,10 +1,7 @@ name: Sync `documentation` directory to ReadMe # Run workflow for every push to the `main` branch -on: - push: - branches: - - main +on: push jobs: sync: From 63b04068349bed2487e34c83f16b67510ab3e3f5 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 09:55:05 -0600 Subject: [PATCH 08/43] docs: add comment --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ab6bfc680..c72af0e62 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,6 +11,7 @@ jobs: uses: actions/checkout@v2.4.0 # Run GitHub Action to sync docs in `documentation` directory + # Page we're syncing: https://docs.readme.com/docs/rdme - name: GitHub Action # Use the `main` branch as ref for GitHub Action # Not recommended, this can break your workflows! From c5b5847363ffad8a6c663ab17101ccf6eba64f89 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 10:00:00 -0600 Subject: [PATCH 09/43] docs: clarify installation slightly further --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4839849dc..832ea6267 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ We recommend installing `rdme` in your project rather than doing a global instal npm install rdme --save-dev ``` -Once installed, we recommend using `npx` (which is included if you have `npm` installed) to prefix all of your CLI commands. For example: +Once installed in your project, we recommend using `npx` (which is included if you have `npm` installed) to prefix all of your CLI commands. For example: ```sh npx rdme validate [file] From 93f742a010e51cf38228c2dfc955356ac081299d Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 10:00:15 -0600 Subject: [PATCH 10/43] docs: update package description --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index c091a9f72..95b1933e9 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "rdme", "version": "6.4.0", - "description": "ReadMe's API CLI", + "description": "The official CLI and GitHub Action wrapper for the ReadMe API.", "license": "MIT", "author": "ReadMe (https://readme.com)", "engines": { From 6bcb3fc44d0efd3bf62e527a8e38a58b5d005237 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 13:03:47 -0600 Subject: [PATCH 11/43] docs: first pass at new docs also making some language tweaks in the main README.md file so messaging and usage is aligned --- README.md | 8 +- documentation/rdme.md | 203 +++++++++++++++++++++++++++++++++++++++++- 2 files changed, 204 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 832ea6267..af36a9d03 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) -`rdme` is the CLI and [GitHub Action](#github-actions) wrapper for [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api). It allows you to sync [OpenAPI](https://spec.openapis.org) and [Swagger](https://swagger.io/specification/v2/) definitions with projects you create on [ReadMe](https://readme.com/). Additionally, you can sync documentation with your project, and manage project versions. +`rdme` is [ReadMe](https://readme.com)'s official command-line interface (CLI) and [GitHub Action](#github-actions) wrapper. It allows you to sync [OpenAPI](https://spec.openapis.org) and [Swagger](https://swagger.io/specification/v2/) definitions with projects you create on [ReadMe](https://readme.com/). You can also access other parts of [ReadMe's RESTful API](https://docs.readme.com/reference/intro-to-the-readme-api), including syncing Markdown documentation with your project and managing project versions. ## Configuration @@ -51,7 +51,7 @@ If you wish to get more information about any command within `rdme`, you can exe -> For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/automatically-sync-api-specification-with-github). +> For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/rdme). For usage in [GitHub Actions](https://docs.github.com/actions), create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: @@ -65,7 +65,7 @@ For usage in [GitHub Actions](https://docs.github.com/actions), create [a new Gi The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command: ```sh -rdme openapi path/to/openapi.json --key=API_KEY --id=OPENAPI_ID +rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID ``` To execute this command via GitHub Actions, the step would look like this: @@ -73,7 +73,7 @@ To execute this command via GitHub Actions, the step would look like this: ```yml - uses: readmeio/rdme@XX with: - rdme: openapi path/to/openapi.json --key=API_KEY --id=OPENAPI_ID + rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID ``` Note that the `@XX` in the above examples refers to the version of `rdme` (e.g. `@7.0`). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). diff --git a/documentation/rdme.md b/documentation/rdme.md index 2ad1d8640..08d957b35 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -1,7 +1,204 @@ --- -title: rdme +title: CLI + GitHub Action Usage +description: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! category: 5f7ce9e3a5504d0414d024c2 -hidden: true --- -Hello Owlbert! + + +If you're anything like us, your documentation process may be a part of a broader [CI/CD](https://en.wikipedia.org/wiki/CI/CD) process. For example, you may want to automatically update your ReadMe guides or API reference every time you've ship new code. Enter [`rdme`](https://github.com/readmeio/rdme): ReadMe's official command-line interface (CLI) and GitHub Action! + +With `rdme`, you can create workflows for a variety of use cases, including: + +- Syncing [OpenAPI/Swagger](https://docs.readme.com/docs/openapi) definitions (with support for bundling external references) 📦 +- Pre-upload validation (including OpenAPI 3.1) ✅ +- Syncing directories of Markdown files 📖 + +## General Setup and Usage + +To see detailed CLI setup instructions and all available commands, check out [the `rdme` GitHub repository](https://github.com/readmeio/rdme#readme). + +### Markdown File Setup + +In order to sync a directory of Markdown files to your guides, you'll need to add certain attributes to the top of each page via a [YAML front matter block](https://jekyllrb.com/docs/front-matter/). See below for an example (using the page you're currently reading!): + +```markdown +--- +title: CLI + GitHub Action Usage +description: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! +category: 5f7ce9e3a5504d0414d024c2 +--- + +If you're anything like us... +``` + +The only required attributes are the `title` and `category`. To determine what your `category` value should be, you can use [the Get all categories endpoint](https://docs.readme.com/reference/getcategories) and grab the `id` value from the response. + +We automatically derive the page's slug via the file name (e.g. the file name `rdme.md` would become `/docs/rdme` in your ReadMe project), but you can override that as well: + +```markdown +--- +title: CLI + GitHub Action Usage +description: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! +category: 5f7ce9e3a5504d0414d024c2 +slug: an-alternative-page-slug-example +--- +``` + +You can also specify several other page attributes in your YAML front matter, such as `hidden` (a boolean which denotes whether your page is published or unpublished). Any attributes you omit will remain unchanged on `rdme` runs. To view the full list of attributes, check out our [`Create doc` endpoint documentation](https://docs.readme.com/reference/createdoc). + +## GitHub Actions Usage + +[GitHub Actions](https://docs.github.com/actions) makes it easy to automatically execute workflows when certain events take place in your GitHub repository (e.g. new code is merged into the default branch, a new pull request is opened, etc.). + + + + +> 📘 Keeping `rdme` up-to-date +> +> Note that the `@XX` in the below examples refers to the version of `rdme` (e.g. `@7.0`), which you can find in [the Marketplace listing](). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). + +For usage in [GitHub Actions](https://docs.github.com/actions), create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: + +```yml +- uses: actions/checkout@v2 +- uses: readmeio/rdme@XX + with: + rdme: [your command here] +``` + +The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command: + +```sh +rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID +``` + +To execute this command via GitHub Actions, the step would look like this: + +```yml +- uses: readmeio/rdme@XX + with: + rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID +``` + +We'll dive into several full GitHub Workflow file examples below! + +### Example: Syncing Markdown Docs + +Not to get too meta on you, but... the page that you're currently reading is actually being synced from the `rdme` GitHub repository via the `rdme` GitHub Action! Here are a few links to the relevant files: + +- [The Markdown source file for the page you're reading](https://github.com/readmeio/rdme/tree/main/docs/rdme.md) +- [The full GitHub Action workflow file that we use to sync the file to docs.readme.com](https://github.com/readmeio/rdme/blob/main/.github/workflows/docs.yml) +- And finally... [the workflow run results](https://github.com/readmeio/rdme/actions/workflows/docs.yml)! + +To recreate this magic in your repository, your GitHub Workflow file will look like this: + +```yml +name: Sync `documentation` directory to ReadMe + +# Run workflow for every push to the `main` branch +on: + push: + branches: + - main + +jobs: + sync: + runs-on: ubuntu-latest + steps: + - name: Checkout this repo + uses: actions/checkout@v2.4.0 + + # Run GitHub Action to sync docs in `documentation` directory + - name: GitHub Action + # We recommend specifying a fixed version, i.e. @7.0 + # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions + uses: readmeio/rdme@XX + with: + rdme: docs ./documentation --key=API_KEY --version=2.0 +``` + +In the example above, every push to the `main` branch will check out your repository's contents and sync the contents of the `documentation` directory with your ReadMe project. + +### Example: Syncing an OpenAPI Definition + +To sync an OpenAPI or Swagger definition, you'll first want to obtain a unique API definition ID from ReadMe so we know which definition you want to update on subsequent re-syncs. You can obtain this API definition ID in one of several ways, but we'll dive into two below: uploading a file directly into the ReadMe dashboard and using the `rdme` CLI locally. + +
+Uploading a file + +Follow [these instructions](https://docs.readme.com/docs/openapi#file-upload) on uploading a new OpenAPI file in the dashboard. Once the file is uploaded, you'll see the following in the API Reference settings of your dashboard (the red outline is where you'll find your API definition ID): + +![](https://files.readme.io/d57b7c8-Screen_Shot_2022-02-23_at_11.54.21_AM.png) + +
+
+Using the rdme CLI + +Alternatively, you can obtain the API definition ID by running the following `rdme` CLI command on your local machine: + +```sh +rdme openapi [path-to-file.json] +``` + +Once you follow the prompts and upload your OpenAPI definition, you'll receive a confirmation message that looks something like this: + +``` +You've successfully updated an OpenAPI file on your ReadMe project! + + http://dash.readme.com/project/{your_project}/v1.0/refs/pet + +To update your OpenAPI or Swagger definition, run the following: + + rdme openapi FILE --key=API_KEY --id=API_DEFINITION_ID +``` + +
+ +Once you've obtained your API definition ID, your full GitHub Workflow file will look something like this: + +```yml +name: Sync OpenAPI definition to ReadMe + +# Run workflow for every push to the `main` branch +on: + push: + branches: + - main + +jobs: + sync: + runs-on: ubuntu-latest + steps: + - name: Checkout this repo + uses: actions/checkout@v2.4.0 + + # Run GitHub Action to sync docs in `documentation` directory + - name: GitHub Action + # We recommend specifying a fixed version, i.e. @7.0 + # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions + uses: readmeio/rdme@XX + with: + rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID +``` + +### Example: Using GitHub Secrets + +> 🚧 Secretly store your ReadMe API Key! +> +> GitHub Actions has [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) to securely store sensitive information so it isn't publicly visible. We **strongly** recommend using these for storing your ReadMe API Key, your API definition ID, and any other secret keys—whether your repository is public or private. You can read more about setting these up [in their documentation](https://docs.github.com/en/actions/security-guides/encrypted-secrets). + +To use a GitHub secret in your `rdme` GitHub Action, first [create a new repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). Let's say you create a new secret key called `README_API_KEY`. The usage in the `rdme` step will look something like this: + +```yml +- uses: readmeio/rdme@XX + with: + rdme: docs ./documentation --key=${{ secrets.README_API_KEY }} --version=2.0 +``` From a132e725ab835ae1f283796ac3b3a3a326778ed1 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 13:07:05 -0600 Subject: [PATCH 12/43] fix: excerpt, not description --- documentation/rdme.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index 08d957b35..e28bb8855 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -1,6 +1,6 @@ --- title: CLI + GitHub Action Usage -description: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! +excerpt: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! category: 5f7ce9e3a5504d0414d024c2 --- @@ -32,7 +32,7 @@ In order to sync a directory of Markdown files to your guides, you'll need to ad ```markdown --- title: CLI + GitHub Action Usage -description: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! +excerpt: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! category: 5f7ce9e3a5504d0414d024c2 --- @@ -46,7 +46,7 @@ We automatically derive the page's slug via the file name (e.g. the file name `r ```markdown --- title: CLI + GitHub Action Usage -description: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! +excerpt: Learn more about `rdme`, ReadMe's official CLI and GitHub Action! category: 5f7ce9e3a5504d0414d024c2 slug: an-alternative-page-slug-example --- From fad527b5bbb7485e39fa74f93c9164ef36d674e8 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 13:08:57 -0600 Subject: [PATCH 13/43] fix: consistent endpoint doc formatting --- documentation/rdme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index e28bb8855..3bbdeb1a1 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -39,7 +39,7 @@ category: 5f7ce9e3a5504d0414d024c2 If you're anything like us... ``` -The only required attributes are the `title` and `category`. To determine what your `category` value should be, you can use [the Get all categories endpoint](https://docs.readme.com/reference/getcategories) and grab the `id` value from the response. +The only required attributes are the `title` and `category`. To determine what your `category` value should be, you can use [the `Get all categories` endpoint](https://docs.readme.com/reference/getcategories) and grab the `id` value from the response. We automatically derive the page's slug via the file name (e.g. the file name `rdme.md` would become `/docs/rdme` in your ReadMe project), but you can override that as well: From 452ebca11573cef9075e3ba387d4cf73875ff1fc Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 13:15:27 -0600 Subject: [PATCH 14/43] docs: add snippet on markdown file formatting --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index af36a9d03..81bf5bf8a 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,8 @@ rdme validate [path-to-file.json] #### Syncing a Folder of Markdown Docs to ReadMe +The Markdown files will require YAML front matter with certain ReadMe documentation attributes. Check out [our docs](https://docs.readme.com/docs/rdme#markdown-file-setup) for more info. + ```sh rdme docs path-to-markdown-files --version={project-version} ``` From 1927853ad4905ae672b0d9fa94f8100fb628881d Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 13:37:55 -0600 Subject: [PATCH 15/43] docs: one more update of this description --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 95b1933e9..0484bd243 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "rdme", "version": "6.4.0", - "description": "The official CLI and GitHub Action wrapper for the ReadMe API.", + "description": "ReadMe's official CLI and GitHub Action wrapper.", "license": "MIT", "author": "ReadMe (https://readme.com)", "engines": { From c4bd19851f14a45cb74bd9fe5c75c65dc2db5085 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 13:38:11 -0600 Subject: [PATCH 16/43] docs: consistent example footer --- documentation/rdme.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/documentation/rdme.md b/documentation/rdme.md index 3bbdeb1a1..101f5ef74 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -189,6 +189,8 @@ jobs: rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID ``` +In the example above, every push to the `main` branch will check out your repository's contents and sync the OpenAPI file located at `./path-to-file.json` with your ReadMe project. + ### Example: Using GitHub Secrets > 🚧 Secretly store your ReadMe API Key! From 9d075bcd26476bb4f6645f357dccfcac1917dc5e Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 13:50:06 -0600 Subject: [PATCH 17/43] chore: remove TODO Co-Authored-By: Jon Ursenbach --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 81bf5bf8a..65aebaced 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,6 @@ If you wish to get more information about any command within `rdme`, you can exe ### GitHub Actions - - > For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/rdme). For usage in [GitHub Actions](https://docs.github.com/actions), create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: From 13ea2f2e95129d984e9be94d7cb8149b5375fc3a Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 15:55:41 -0600 Subject: [PATCH 18/43] ci: dynamically update docs on readme let's hope this works! --- .github/workflows/docs.yml | 25 +++++++++++++++++++++++-- bin/set-version-output | 11 +++++++++++ documentation/rdme.md | 23 +++++++++++++---------- 3 files changed, 47 insertions(+), 12 deletions(-) create mode 100755 bin/set-version-output diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c72af0e62..2c3260fc2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -10,8 +10,29 @@ jobs: - name: Checkout this repo uses: actions/checkout@v2.4.0 - # Run GitHub Action to sync docs in `documentation` directory - # Page we're syncing: https://docs.readme.com/docs/rdme + # Let's dynamically update our docs with the latest version of rdme! + # Note that these next two steps are not required + # in order to sync your docs to ReadMe. + + # First, we run a script that grabs the current version from + # our package.json and sets it as a GitHub Action output! + - name: Retrieve `rdme` version from package.json + id: rdme-version + run: ./bin/set-version-output + + # Next, we use this output to do a simple find and replace! + - name: Find and replace version placeholders in docs + uses: jacobtomlinson/gha-find-replace@v2 + with: + find: 'RDME_VERSION' + replace: ${{ steps.rdme-version.outputs.RDME_VERSION }} + regex: false + include: documentation/ + + # And finally, with our updated documentation, + # we run the `rdme` GitHub Action to sync the Markdown file + # in the `documentation` directory. + # Here's the page we're syncing: https://docs.readme.com/docs/rdme - name: GitHub Action # Use the `main` branch as ref for GitHub Action # Not recommended, this can break your workflows! diff --git a/bin/set-version-output b/bin/set-version-output new file mode 100755 index 000000000..662d543ad --- /dev/null +++ b/bin/set-version-output @@ -0,0 +1,11 @@ +#! /usr/bin/env node + +const pkg = require('../package.json'); + +const name = 'RDME_VERSION'; + +/** + * Sets output parameter for GitHub Actions workflow + * Docs: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter + */ +console.log(`::set-output name=${name}::${pkg.version}`); // eslint-disable-line no-console diff --git a/documentation/rdme.md b/documentation/rdme.md index 101f5ef74..718bc8511 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -11,8 +11,14 @@ This Markdown page is syncing to ReadMe via the `rdme GitHub Action 🦉 Check out the "Syncing Markdown Docs" example below, and peep the resulting page in our docs: https://docs.readme.com/docs/rdme +We also do some fancy little find-and-replace action to swap out every instance +of `RDME_VERSION` below with the latest version of rdme. +Check out `.github/workflows/docs.yml` for more info on this! + --> +[![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) + If you're anything like us, your documentation process may be a part of a broader [CI/CD](https://en.wikipedia.org/wiki/CI/CD) process. For example, you may want to automatically update your ReadMe guides or API reference every time you've ship new code. Enter [`rdme`](https://github.com/readmeio/rdme): ReadMe's official command-line interface (CLI) and GitHub Action! With `rdme`, you can create workflows for a variety of use cases, including: @@ -58,18 +64,15 @@ You can also specify several other page attributes in your YAML front matter, su [GitHub Actions](https://docs.github.com/actions) makes it easy to automatically execute workflows when certain events take place in your GitHub repository (e.g. new code is merged into the default branch, a new pull request is opened, etc.). - - - > 📘 Keeping `rdme` up-to-date > -> Note that the `@XX` in the below examples refers to the version of `rdme` (e.g. `@7.0`), which you can find in [the Marketplace listing](). We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). +> Note that the `@RDME_VERSION` in the below examples is the latest version of `rdme`. We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). For usage in [GitHub Actions](https://docs.github.com/actions), create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: ```yml - uses: actions/checkout@v2 -- uses: readmeio/rdme@XX +- uses: readmeio/rdme@RDME_VERSION with: rdme: [your command here] ``` @@ -83,7 +86,7 @@ rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID To execute this command via GitHub Actions, the step would look like this: ```yml -- uses: readmeio/rdme@XX +- uses: readmeio/rdme@RDME_VERSION with: rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID ``` @@ -118,9 +121,9 @@ jobs: # Run GitHub Action to sync docs in `documentation` directory - name: GitHub Action - # We recommend specifying a fixed version, i.e. @7.0 + # We recommend specifying a fixed version, i.e. @RDME_VERSION # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions - uses: readmeio/rdme@XX + uses: readmeio/rdme@RDME_VERSION with: rdme: docs ./documentation --key=API_KEY --version=2.0 ``` @@ -184,7 +187,7 @@ jobs: - name: GitHub Action # We recommend specifying a fixed version, i.e. @7.0 # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions - uses: readmeio/rdme@XX + uses: readmeio/rdme@RDME_VERSION with: rdme: openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID ``` @@ -200,7 +203,7 @@ In the example above, every push to the `main` branch will check out your reposi To use a GitHub secret in your `rdme` GitHub Action, first [create a new repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). Let's say you create a new secret key called `README_API_KEY`. The usage in the `rdme` step will look something like this: ```yml -- uses: readmeio/rdme@XX +- uses: readmeio/rdme@RDME_VERSION with: rdme: docs ./documentation --key=${{ secrets.README_API_KEY }} --version=2.0 ``` From 5c1d0c8bdf5d4df76766317c8745e3c5565179b6 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 15:59:19 -0600 Subject: [PATCH 19/43] fix: glob --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2c3260fc2..2e11b52e2 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -27,7 +27,7 @@ jobs: find: 'RDME_VERSION' replace: ${{ steps.rdme-version.outputs.RDME_VERSION }} regex: false - include: documentation/ + include: documentation/* # And finally, with our updated documentation, # we run the `rdme` GitHub Action to sync the Markdown file From 48ad10829f050005cfd5c13b1f904c539e840d01 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 16:03:58 -0600 Subject: [PATCH 20/43] docs: more cleanup --- .github/workflows/docs.yml | 6 +++--- documentation/rdme.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2e11b52e2..3c267b809 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -34,9 +34,9 @@ jobs: # in the `documentation` directory. # Here's the page we're syncing: https://docs.readme.com/docs/rdme - name: GitHub Action - # Use the `main` branch as ref for GitHub Action - # Not recommended, this can break your workflows! - # We recommend specifying a fixed version + # We use the `main` branch as ref for GitHub Action + # This is NOT recommended, as it can break your workflows without notice! + # We recommend specifying a fixed version, i.e. @7.0 # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions uses: readmeio/rdme@main with: diff --git a/documentation/rdme.md b/documentation/rdme.md index 718bc8511..107ceec41 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -101,7 +101,7 @@ Not to get too meta on you, but... the page that you're currently reading is act - [The full GitHub Action workflow file that we use to sync the file to docs.readme.com](https://github.com/readmeio/rdme/blob/main/.github/workflows/docs.yml) - And finally... [the workflow run results](https://github.com/readmeio/rdme/actions/workflows/docs.yml)! -To recreate this magic in your repository, your GitHub Workflow file will look like this: +To recreate this magic in your repository, your GitHub Workflow file will look something like this: ```yml name: Sync `documentation` directory to ReadMe From 3624e11efdf37ba6bda30f55e8911e34ea10d456 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 16:07:27 -0600 Subject: [PATCH 21/43] chore: replace one more placeholder --- documentation/rdme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index 107ceec41..79d052b1a 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -185,7 +185,7 @@ jobs: # Run GitHub Action to sync docs in `documentation` directory - name: GitHub Action - # We recommend specifying a fixed version, i.e. @7.0 + # We recommend specifying a fixed version, i.e. @RDME_VERSION # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions uses: readmeio/rdme@RDME_VERSION with: From 6f5364aecaf21c66433096b99f9a83d181ba3f4c Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 16:30:00 -0600 Subject: [PATCH 22/43] docs: fix comment --- documentation/rdme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index 79d052b1a..115ad383f 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -183,7 +183,7 @@ jobs: - name: Checkout this repo uses: actions/checkout@v2.4.0 - # Run GitHub Action to sync docs in `documentation` directory + # Run GitHub Action to sync OpenAPI file at [path-to-file.json] - name: GitHub Action # We recommend specifying a fixed version, i.e. @RDME_VERSION # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions From b3ef8f2ff99ab448a3faa5ebb49044e4d5df4076 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 23 Feb 2022 17:08:18 -0600 Subject: [PATCH 23/43] docs: rearrange status badges --- documentation/rdme.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index 115ad383f..0d2ace384 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -17,10 +17,10 @@ Check out `.github/workflows/docs.yml` for more info on this! --> -[![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) - If you're anything like us, your documentation process may be a part of a broader [CI/CD](https://en.wikipedia.org/wiki/CI/CD) process. For example, you may want to automatically update your ReadMe guides or API reference every time you've ship new code. Enter [`rdme`](https://github.com/readmeio/rdme): ReadMe's official command-line interface (CLI) and GitHub Action! +[![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) + With `rdme`, you can create workflows for a variety of use cases, including: - Syncing [OpenAPI/Swagger](https://docs.readme.com/docs/openapi) definitions (with support for bundling external references) 📦 From 9e895ffc69504b373a9d5593c6d44219d52b479e Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 24 Feb 2022 16:17:55 -0600 Subject: [PATCH 24/43] Update documentation/rdme.md Co-authored-by: Dom Harrington --- documentation/rdme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index 0d2ace384..3a60ec45a 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -7,7 +7,7 @@ category: 5f7ce9e3a5504d0414d024c2 -If you're anything like us, your documentation process may be a part of a broader [CI/CD](https://en.wikipedia.org/wiki/CI/CD) process. For example, you may want to automatically update your ReadMe guides or API reference every time you've ship new code. Enter [`rdme`](https://github.com/readmeio/rdme): ReadMe's official command-line interface (CLI) and GitHub Action! +If you're anything like us, your documentation process may be a part of a broader CI/CD process. For example, you may want to automatically update your ReadMe guides or API reference every time you've ship new code. Enter `rdme`: ReadMe's official command-line interface (CLI) and GitHub Action! [![npm](https://img.shields.io/npm/v/rdme)](https://npm.im/rdme) [![Build](https://github.com/readmeio/rdme/workflows/CI/badge.svg)](https://github.com/readmeio/rdme) @@ -68,7 +68,7 @@ You can also specify several other page attributes in your YAML front matter, su > > Note that the `@RDME_VERSION` in the below examples is the latest version of `rdme`. We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot). -For usage in [GitHub Actions](https://docs.github.com/actions), create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: +For usage in GitHub Actions, create [a new GitHub Workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: ```yml - uses: actions/checkout@v2 From fc8ecdde25ffb8a39d74629946fb0a7586e402f6 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 25 Feb 2022 16:57:59 -0600 Subject: [PATCH 29/43] docs: troubleshooting docs --- documentation/rdme.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/documentation/rdme.md b/documentation/rdme.md index acf463bd0..e0f9e4e4c 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -207,3 +207,29 @@ To use a GitHub secret in your `rdme` GitHub Action, first [create a new reposit with: rdme: docs ./documentation --key=${{ secrets.README_API_KEY }} --version=2.0 ``` + +## Troubleshooting + +If you're running into unexpected behavior with `rdme` and need to troubleshoot the issue, you have several debug logging options available. We may ask for these logs (as well as a copy of your OpenAPI definition) when you contact our support team. + +### Troubleshooting CLI + +If you're troubleshooting issues with the CLI (or in some non-GitHub Actions environment), you can use the `DEBUG` environmental variable to print helpful debugging info to the console: + +```sh +DEBUG=rdme* rdme openapi [path-to-file.json] +``` + +Note that this should only be used for development/debugging purposes and should not be enabled in production environments. + +### Troubleshooting GitHub Actions + +If you're troubleshooting issues in a GitHub Actions environment, you can enable [step debug logs](https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging#enabling-step-debug-logging) in your GitHub Actions workflow by [setting the repository secret](https://docs.github.com/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) `ACTIONS_STEP_DEBUG` to `true`. For more information on accessing, downloading, and deleting logs, check out [GitHub's documentation](https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). + +> 🚧 Debug Logs May Contain Sensitive Information +> +> Enabling step debug logs will produce comprehensive logging for **all** of your GitHub Action workflow steps. While GitHub automatically masks any sensitive information you load in with [secrets](#example-using-github-secrets), there might be other sensitive information that's exposed. Anybody with read access to the repository will be able to see these logs. +> +> We **strongly recommend** that you only enable step debug logs in private repositories. If working in a public repository, we suggest recreating your GitHub workflow setup (e.g. with your GitHub workflow files, OpenAPI definitions, and anything else you need for syncing to ReadMe) in a separate private repository for testing purposes before enabling this setting. +> +> If you do enable step debug logs in your repository and your logs produce sensitive information, here are [GitHub's docs on deleting logs](https://docs.github.com/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs#deleting-logs). From 12f2d71838471c8ff2a14da9679213985d020a4b Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 25 Feb 2022 17:01:12 -0600 Subject: [PATCH 30/43] chore: shorten title juuuust a lil bit --- documentation/rdme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index e0f9e4e4c..14bdd2228 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -1,5 +1,5 @@ --- -title: Syncing Docs via CLI / GitHub Action +title: Syncing Docs via CLI / GitHub excerpt: Update your docs automatically with `rdme`, ReadMe's official CLI and GitHub Action! category: 5f7ce9e3a5504d0414d024c2 --- From 8c04e6fc3c247da5e33247cff4eb3ba2254f797f Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 25 Feb 2022 17:11:18 -0600 Subject: [PATCH 31/43] chore: temporarily disable workflow --- .github/workflows/docs.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3c267b809..27cba5d28 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,11 +33,11 @@ jobs: # we run the `rdme` GitHub Action to sync the Markdown file # in the `documentation` directory. # Here's the page we're syncing: https://docs.readme.com/docs/rdme - - name: GitHub Action - # We use the `main` branch as ref for GitHub Action - # This is NOT recommended, as it can break your workflows without notice! - # We recommend specifying a fixed version, i.e. @7.0 - # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions - uses: readmeio/rdme@main - with: - rdme: docs ./documentation --key=${{ secrets.README_PROD_PROJECT_API_KEY }} --version=2.0 + # - name: GitHub Action + # # We use the `main` branch as ref for GitHub Action + # # This is NOT recommended, as it can break your workflows without notice! + # # We recommend specifying a fixed version, i.e. @7.0 + # # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions + # uses: readmeio/rdme@main + # with: + # rdme: docs ./documentation --key=${{ secrets.README_PROD_PROJECT_API_KEY }} --version=2.0 From ddbc78692d46e13838d98e7976b3c42d81e4c4aa Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 25 Feb 2022 17:12:17 -0600 Subject: [PATCH 32/43] docs: backfill legacy doc --- documentation/legacy-github-action.md | 116 ++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 documentation/legacy-github-action.md diff --git a/documentation/legacy-github-action.md b/documentation/legacy-github-action.md new file mode 100644 index 000000000..8c6d3745b --- /dev/null +++ b/documentation/legacy-github-action.md @@ -0,0 +1,116 @@ +--- +category: 5f7ce9e3a5504d0414d024c2 +hidden: true +slug: automatically-sync-api-specification-with-github +title: OpenAPI + GitHub Sync [DEPRECATED] +--- + +> ❗️Deprecated in favor of [`rdme`](https://docs.readme.com/docs/rdme), our new GitHub Action 🔁 +> +> This GitHub Action has been deprecated in favor of our newer (and more fully-featured) GitHub Action, [`rdme`](https://docs.readme.com/docs/rdme), which has support for syncing OpenAPI files, syncing Markdown files, and much more. +> +> If you previously used ReadMe's [legacy GitHub Action](#legacy-docs), you are welcome to continue doing so if it's working for you. It will continue to run in existing workflows for the foreseeable future, but all development and support for this tool has been closed. To ensure your workflows continue to operate and are taking advantage of our latest features, we strongly recommend switching to [`rdme`](https://docs.readme.com/docs/rdme). Check out the migration guide below! + +## Migrating to `rdme` + +If you previously had a GitHub Workflow file set up that used this action to sync your OpenAPI file to ReadMe, you had a step in your workflow that looked something like this: + +```yml +- uses: readmeio/github-readme-sync@v2 + with: + readme-oas-key: API_KEY:API_DEFINITION_ID + oas-file-path: path/to/file.json + api-version: 'v1.0.0' +``` + +where `API_KEY` was your project API key and the `API_DEFINITION_ID` was your API definition ID in the dashboard. + +For migrating to the `rdme`-based GitHub Action, simply modify the step to look like this: + +```yml +- uses: readmeio/rdme@XX + with: + rdme: openapi path/to/file.json --key=API_KEY --id=API_DEFINITION_ID +``` + +There are two things to note: + +1. This workflow will infer the `api-version` based on the `API_DEFINITION_ID` parameter that you pass in, so the API version parameter is no longer needed here. +2. The `@XX` refers to the latest version of `rdme`, which you can find on [the GitHub Action Marketplace page](TKTK). As an example, the latest version as of this writing is `7.0`, so you would replace the `XX` in the above snippet with `7.0`. To ensure you're getting the latest features and security updates, we strongly recommend setting up [Dependabot](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot) to keep this package up-to-date. + +
+ +View the legacy docs below! + +## Legacy Docs + +With [GitHub Actions](https://github.com/features/actions), it's super easy to automatically sync your OpenAPI document whenever changes occur in your GitHub repo! + +> ❗️Deprecated! Do not use this section for new GitHub Action workflows +> +> Just as a reminder, the `readmeio/github-readme-sync` GitHub Action that's described below is now deprecated. The instructions are preserved for posterity. We strongly recommend all new and existing workflows to use our newest GitHub Action: [`rdme`](https://docs.readme.com/docs/rdme)! + +Just create a new file in your GitHub repository called `.github/workflows/readme-github-sync.yml` and populate it with the template below. You only fill in one parameter from the ReadMe Dashboard and you'll be good to go! + +Any subsequent commits to the `main` or `master` branch (whichever is your default branch—you can also specify any GitHub event of your choice—see [GitHub's docs](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#on) for more info) will automatically trigger the sync process and upload your specified OpenAPI file to ReadMe. + +```yaml .github/workflows/readme-api-sync.yml +name: Sync OAS to ReadMe +on: + push: + branches: + - main + - master +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: readmeio/github-readme-sync@v2 + with: + readme-oas-key: 'unique-key-from-dashboard' + + # OPTIONAL CONFIG, use if necessary + # oas-file-path: './swagger.json' + # api-version: 'v1.0.0' +``` + +> 🚧 Public Repo? Secretly store your ReadMe API Key! +> +> GitHub Actions have a way to securely store sensitive information (such as your ReadMe API Key and API Specification ID), so it isn't publicly visible. You can read more [in their documentation](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets). + +| Parameter | Description | +| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| readme-oas-key | **Required** This value can be obtained from the project dashboard when adding a new API to your project. For migrating existing APIs, see [here](#migrating-existing-apis-to-github-sync). | +| oas-file-path | **Optional** Path to OpenAPI document that will be synced to ReadMe. By default, we try to find the spec file in the directory automatically (i.e. if it's a JSON or YAML file with filenames like `swagger`, `oas`, or `openapi`). | +| api-version | **Optional** Existing ReadMe Version to upload to. By default, we use the version specified in the spec file.[Versions in ReadMe](doc:versions) and [specifying the version in the OpenAPI Info object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#info-object) | + +### Migrating Existing APIs to GitHub Sync + +If you want to migrate APIs that are already synced into ReadMe via another mechanism, it's super easy! The value for `readme-oas-key` is your [ReadMe Project API Key](https://docs.readme.com/developers/docs/authentication#api-key-quick-start) and the API Specification ID (pictured below) separated by a colon (i.e. `apiKey:apiSpecId`). + +![](https://files.readme.io/9a89ed3-id.png) + +Use `readme-oas-key` in your `.github/workflows/readme-github-sync.yml` file and any subsequent pushes to the `master` branch (or whichever branch(es) you specify in your workflow file) in that GitHub repository will sync that OpenAPI file to ReadMe! + +> 📘 Keeping Your GitHub Action Up-to-Date +> +> To ensure that you're on the latest version of our GitHub Action (along with all of your project dependencies), we highly recommend [setting up Dependabot](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/enabling-and-disabling-version-updates), which automatically updates your project dependencies (including this one!). As a fallback, we recommend keeping your version of the `github-readme-sync` package set to `v2` as denoted above, which ensures that your workflow will execute the latest available version within the version 2 range. + +### Troubleshooting + +If you're seeing failures with the GitHub Action and need to troubleshoot the issue, we provide comprehensive step-by-step debug logs. We may ask for these logs (as well as a copy of your API specification file) when you contact our support team. You can enable [Step Debug Logs](https://github.com/actions/toolkit/blob/main/docs/action-debugging.md#step-debug-logs) in your GitHub Actions workflow by [setting the repository secret](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets#creating-encrypted-secrets) `ACTIONS_STEP_DEBUG` to `true`. For more information on accessing, downloading, and deleting logs, check out [GitHub's documentation](https://docs.github.com/en/free-pro-team@latest/actions/managing-workflow-runs/using-workflow-run-logs). + +> 🚧 Debug Logs May Contain Sensitive Information +> +> Enabling [Step Debug Logs](https://github.com/actions/toolkit/blob/main/docs/action-debugging.md#step-debug-logs) will produce comprehensive logging for **all** of your GitHub Action workflows. While we sanitize all logging output to prevent API keys from being visible, the logs may contain other sensitive information (from ReadMe and any other services that you use). Anybody with read access to the repository will be able to see these logs. +> +> We **strongly recommend** that you only enable this setting in private repositories. If working in a public repository, we suggest creating a separate private repository with your GitHub workflow and OpenAPI/Swagger files before enabling this debugger. +> +> If you do enable Step Debug Logs in your repository and your logs produce sensitive information, here are [GitHub's docs on deleting logs](https://docs.github.com/en/free-pro-team@latest/actions/managing-workflow-runs/using-workflow-run-logs#deleting-logs). + +### Example + +Want to see the GitHub Action in action? Check out this example repository: [kanadgupta/metrotransit-nextrip-oas](https://github.com/kanadgupta/metrotransit-nextrip-oas) + +To see an example where multiple OpenAPI/Swagger files are synced in the same repository, check out [jesseyowell/oas-test-files](https://github.com/jesseyowell/oas-test-files). From 6757bce0fcd61721ad0d0dd325cded457aa304fe Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 25 Feb 2022 17:13:53 -0600 Subject: [PATCH 33/43] docs: backfill RDME_VERSION --- documentation/legacy-github-action.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/legacy-github-action.md b/documentation/legacy-github-action.md index 8c6d3745b..f2fe2ecde 100644 --- a/documentation/legacy-github-action.md +++ b/documentation/legacy-github-action.md @@ -28,7 +28,7 @@ where `API_KEY` was your project API key and the `API_DEFINITION_ID` was your AP For migrating to the `rdme`-based GitHub Action, simply modify the step to look like this: ```yml -- uses: readmeio/rdme@XX +- uses: readmeio/rdme@RDME_VERSION with: rdme: openapi path/to/file.json --key=API_KEY --id=API_DEFINITION_ID ``` @@ -36,7 +36,7 @@ For migrating to the `rdme`-based GitHub Action, simply modify the step to look There are two things to note: 1. This workflow will infer the `api-version` based on the `API_DEFINITION_ID` parameter that you pass in, so the API version parameter is no longer needed here. -2. The `@XX` refers to the latest version of `rdme`, which you can find on [the GitHub Action Marketplace page](TKTK). As an example, the latest version as of this writing is `7.0`, so you would replace the `XX` in the above snippet with `7.0`. To ensure you're getting the latest features and security updates, we strongly recommend setting up [Dependabot](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot) to keep this package up-to-date. +2. `@RDME_VERSION` is the latest version of `rdme`. To ensure you're getting the latest features and security updates, we strongly recommend setting up [Dependabot](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot) to keep this package up-to-date.
From 1af8438f0fdb9381bc585f5800d04fca18fde316 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Sat, 26 Feb 2022 11:37:25 -0600 Subject: [PATCH 34/43] chore: adjust callout title --- documentation/legacy-github-action.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/legacy-github-action.md b/documentation/legacy-github-action.md index f2fe2ecde..727a026b5 100644 --- a/documentation/legacy-github-action.md +++ b/documentation/legacy-github-action.md @@ -46,7 +46,7 @@ There are two things to note: With [GitHub Actions](https://github.com/features/actions), it's super easy to automatically sync your OpenAPI document whenever changes occur in your GitHub repo! -> ❗️Deprecated! Do not use this section for new GitHub Action workflows +> ❗️Deprecated workflow instructions below > > Just as a reminder, the `readmeio/github-readme-sync` GitHub Action that's described below is now deprecated. The instructions are preserved for posterity. We strongly recommend all new and existing workflows to use our newest GitHub Action: [`rdme`](https://docs.readme.com/docs/rdme)! From afcd138e865ff763e65facd2ccc4d33375f4d8bc Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 16:42:53 -0600 Subject: [PATCH 35/43] chore: add comment to match rdme.md --- documentation/legacy-github-action.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/documentation/legacy-github-action.md b/documentation/legacy-github-action.md index 727a026b5..9eb8850e1 100644 --- a/documentation/legacy-github-action.md +++ b/documentation/legacy-github-action.md @@ -5,6 +5,14 @@ slug: automatically-sync-api-specification-with-github title: OpenAPI + GitHub Sync [DEPRECATED] --- + + > ❗️Deprecated in favor of [`rdme`](https://docs.readme.com/docs/rdme), our new GitHub Action 🔁 > > This GitHub Action has been deprecated in favor of our newer (and more fully-featured) GitHub Action, [`rdme`](https://docs.readme.com/docs/rdme), which has support for syncing OpenAPI files, syncing Markdown files, and much more. From 4988aa0e5baaa129bf6b9202ca7edb8906a072a9 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 17:45:14 -0600 Subject: [PATCH 36/43] feat: add node.js version find/replace --- .github/workflows/docs.yml | 14 +++++++++++--- __tests__/lib/getNodeVersion.test.js | 11 +++++++++++ bin/set-version-output | 9 ++++++--- src/lib/getNodeVersion.js | 15 +++++++++++++++ 4 files changed, 43 insertions(+), 6 deletions(-) create mode 100644 __tests__/lib/getNodeVersion.test.js create mode 100644 src/lib/getNodeVersion.js diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 3c267b809..87a799974 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -14,13 +14,21 @@ jobs: # Note that these next two steps are not required # in order to sync your docs to ReadMe. - # First, we run a script that grabs the current version from - # our package.json and sets it as a GitHub Action output! + # First, we run a script that sets a few outputs: + # our package version and our Node.js version. - name: Retrieve `rdme` version from package.json id: rdme-version run: ./bin/set-version-output - # Next, we use this output to do a simple find and replace! + # Next, we use this output to do a few find/replaces! + - name: Find and replace version placeholders in docs + uses: jacobtomlinson/gha-find-replace@v2 + with: + find: 'NODE_VERSION' + replace: ${{ steps.rdme-version.outputs.NODE_VERSION }} + regex: false + include: documentation/* + - name: Find and replace version placeholders in docs uses: jacobtomlinson/gha-find-replace@v2 with: diff --git a/__tests__/lib/getNodeVersion.test.js b/__tests__/lib/getNodeVersion.test.js new file mode 100644 index 000000000..2fc7c60d0 --- /dev/null +++ b/__tests__/lib/getNodeVersion.test.js @@ -0,0 +1,11 @@ +const getNodeVersion = require('../../src/lib/getNodeVersion'); +const pkg = require('../../package.json'); +const semver = require('semver'); + +describe('#getNodeVersion()', () => { + it('should extract version that matches range in package.json', () => { + const version = parseInt(getNodeVersion(), 10); + const cleanedVersion = semver.valid(semver.coerce(version)); + expect(semver.satisfies(cleanedVersion, pkg.engines.node)).toBe(true); + }); +}); diff --git a/bin/set-version-output b/bin/set-version-output index 662d543ad..0779ff36b 100755 --- a/bin/set-version-output +++ b/bin/set-version-output @@ -1,11 +1,14 @@ #! /usr/bin/env node +const getNodeVersion = require('../src/lib/getNodeVersion'); const pkg = require('../package.json'); -const name = 'RDME_VERSION'; +const name1 = 'RDME_VERSION'; +const name2 = 'NODE_VERSION'; /** - * Sets output parameter for GitHub Actions workflow + * Sets output parameters for GitHub Actions workflow * Docs: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter */ -console.log(`::set-output name=${name}::${pkg.version}`); // eslint-disable-line no-console +console.log(`::set-output name=${name1}::${pkg.version}`); // eslint-disable-line no-console +console.log(`::set-output name=${name2}::${getNodeVersion()}`); // eslint-disable-line no-console diff --git a/src/lib/getNodeVersion.js b/src/lib/getNodeVersion.js new file mode 100644 index 000000000..3767c1f94 --- /dev/null +++ b/src/lib/getNodeVersion.js @@ -0,0 +1,15 @@ +const pkg = require('../../package.json'); + +/** + * @example 14 + * @returns {String} The minimum major Node.js version specified in the package.json + */ +function extractNodeVersion() { + const { node } = pkg.engines; + + const match = Array.from(node.matchAll(/\d+/g)).pop(); + + return match; +} + +module.exports = extractNodeVersion; From 30a099c4be446e0cb0da837d1aaa2fdb7dec484f Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 18:07:09 -0600 Subject: [PATCH 37/43] docs: first pass at CI environments stuff Let's hope this works... --- documentation/rdme.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/documentation/rdme.md b/documentation/rdme.md index 14bdd2228..20b4e7c3e 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -208,6 +208,28 @@ To use a GitHub secret in your `rdme` GitHub Action, first [create a new reposit rdme: docs ./documentation --key=${{ secrets.README_API_KEY }} --version=2.0 ``` +## Usage in Other CI Environments + +Since `rdme` is a command-line tool at its core, you can use `rdme` to sync your documentation from virtually any CI/CD environment that runs shell commands—[Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/), [GitLab CI/CD](https://docs.gitlab.com/ee/ci/), you name it! You can do this by invoking `rdme` with `npx -y rdme@RDME_VERSION` in a Node.js environment. See below for a few simple examples. + +```yml Bitbucket Pipelines (bitbucket-pipelines.yml) +image: node:NODE_VERSION +pipelines: + default: + - step: + script: + - npx -y rdme@RDME_VERSION openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID +``` +```yml GitLab CI (rdme-sync.gitlab-ci.yml) +# Official framework image. Look for the different tagged releases at: +# https://hub.docker.com/r/library/node/tags/ +image: node:NODE_VERSION + +sync-via-rdme: + script: + - npx -y rdme@RDME_VERSION openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID +``` + ## Troubleshooting If you're running into unexpected behavior with `rdme` and need to troubleshoot the issue, you have several debug logging options available. We may ask for these logs (as well as a copy of your OpenAPI definition) when you contact our support team. From 812724454b2a11a96ee2bd260ee63a1c8bacace8 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 18:09:47 -0600 Subject: [PATCH 38/43] chore: rename steps --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 87a799974..b1758cf36 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -21,7 +21,7 @@ jobs: run: ./bin/set-version-output # Next, we use this output to do a few find/replaces! - - name: Find and replace version placeholders in docs + - name: Find and replace Node.js version placeholders uses: jacobtomlinson/gha-find-replace@v2 with: find: 'NODE_VERSION' @@ -29,7 +29,7 @@ jobs: regex: false include: documentation/* - - name: Find and replace version placeholders in docs + - name: Find and replace `rdme` version placeholders uses: jacobtomlinson/gha-find-replace@v2 with: find: 'RDME_VERSION' From 02b7df44f987d4a7c68a9211b56e4629a0187be6 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 18:11:04 -0600 Subject: [PATCH 39/43] chore: add comment, try reformatting --- documentation/rdme.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/documentation/rdme.md b/documentation/rdme.md index 20b4e7c3e..b72c10053 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -213,6 +213,8 @@ To use a GitHub secret in your `rdme` GitHub Action, first [create a new reposit Since `rdme` is a command-line tool at its core, you can use `rdme` to sync your documentation from virtually any CI/CD environment that runs shell commands—[Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/), [GitLab CI/CD](https://docs.gitlab.com/ee/ci/), you name it! You can do this by invoking `rdme` with `npx -y rdme@RDME_VERSION` in a Node.js environment. See below for a few simple examples. ```yml Bitbucket Pipelines (bitbucket-pipelines.yml) +# Official framework image. Look for the different tagged releases at: +# https://hub.docker.com/r/library/node/tags/ image: node:NODE_VERSION pipelines: default: @@ -220,6 +222,7 @@ pipelines: script: - npx -y rdme@RDME_VERSION openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID ``` + ```yml GitLab CI (rdme-sync.gitlab-ci.yml) # Official framework image. Look for the different tagged releases at: # https://hub.docker.com/r/library/node/tags/ From 30c9179fdbe5a11c46377f0148abd692eef1eaf1 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 18:14:52 -0600 Subject: [PATCH 40/43] chore: fix code block formatting well... this is annoying as hell --- documentation/rdme.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index b72c10053..f86890e4c 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -212,6 +212,8 @@ To use a GitHub secret in your `rdme` GitHub Action, first [create a new reposit Since `rdme` is a command-line tool at its core, you can use `rdme` to sync your documentation from virtually any CI/CD environment that runs shell commands—[Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/), [GitLab CI/CD](https://docs.gitlab.com/ee/ci/), you name it! You can do this by invoking `rdme` with `npx -y rdme@RDME_VERSION` in a Node.js environment. See below for a few simple examples. + + ```yml Bitbucket Pipelines (bitbucket-pipelines.yml) # Official framework image. Look for the different tagged releases at: # https://hub.docker.com/r/library/node/tags/ @@ -222,7 +224,6 @@ pipelines: script: - npx -y rdme@RDME_VERSION openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID ``` - ```yml GitLab CI (rdme-sync.gitlab-ci.yml) # Official framework image. Look for the different tagged releases at: # https://hub.docker.com/r/library/node/tags/ From 839260387b35152d25baa46c78e57d0d1cfd0f28 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 18:35:52 -0600 Subject: [PATCH 41/43] ci(docs): restore on step so it only runs on `main` --- .github/workflows/docs.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b1758cf36..85d27a8f0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,7 +1,10 @@ name: Sync `documentation` directory to ReadMe # Run workflow for every push to the `main` branch -on: push +on: + push: + branches: + - main jobs: sync: From 9c9a422482b2e8ab92b37cacc41705936890deb2 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 18:58:09 -0600 Subject: [PATCH 42/43] Update src/lib/getNodeVersion.js Co-authored-by: Jon Ursenbach --- src/lib/getNodeVersion.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib/getNodeVersion.js b/src/lib/getNodeVersion.js index 3767c1f94..0fde1279d 100644 --- a/src/lib/getNodeVersion.js +++ b/src/lib/getNodeVersion.js @@ -2,7 +2,7 @@ const pkg = require('../../package.json'); /** * @example 14 - * @returns {String} The minimum major Node.js version specified in the package.json + * @returns {String} The maximum major Node.js version specified in the package.json */ function extractNodeVersion() { const { node } = pkg.engines; From 74635fa42bcd596651b984c0dbe0ff597f0b82a6 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Mon, 28 Feb 2022 19:03:05 -0600 Subject: [PATCH 43/43] revert: unskip step --- .github/workflows/docs.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 8aeeee293..85d27a8f0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -44,11 +44,11 @@ jobs: # we run the `rdme` GitHub Action to sync the Markdown file # in the `documentation` directory. # Here's the page we're syncing: https://docs.readme.com/docs/rdme - # - name: GitHub Action - # # We use the `main` branch as ref for GitHub Action - # # This is NOT recommended, as it can break your workflows without notice! - # # We recommend specifying a fixed version, i.e. @7.0 - # # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions - # uses: readmeio/rdme@main - # with: - # rdme: docs ./documentation --key=${{ secrets.README_PROD_PROJECT_API_KEY }} --version=2.0 + - name: GitHub Action + # We use the `main` branch as ref for GitHub Action + # This is NOT recommended, as it can break your workflows without notice! + # We recommend specifying a fixed version, i.e. @7.0 + # Docs: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#example-using-versioned-actions + uses: readmeio/rdme@main + with: + rdme: docs ./documentation --key=${{ secrets.README_PROD_PROJECT_API_KEY }} --version=2.0