docs: add GitHub Actions guidance (#439)

* docs: add GitHub Actions guidance * Update README.md Co-authored-by: Jon Ursenbach <[email protected]> * chore: PR feedback Co-Authored-By: Ryan Park <[email protected]> * chore: more docs cleanup * chore: cleanup rearrange some links, remove language from GitHub docs URLs * ci: add workflow for syncing docs to ReadMe! * 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 <[email protected]> * docs: add comment * docs: clarify installation slightly further * docs: update package description * docs: first pass at new docs also making some language tweaks in the main README.md file so messaging and usage is aligned * fix: excerpt, not description * fix: consistent endpoint doc formatting * docs: add snippet on markdown file formatting * docs: one more update of this description * docs: consistent example footer * chore: remove TODO Co-Authored-By: Jon Ursenbach <[email protected]> * ci: dynamically update docs on readme let's hope this works! * fix: glob * docs: more cleanup * chore: replace one more placeholder * docs: fix comment * docs: rearrange status badges * Update documentation/rdme.md Co-authored-by: Dom Harrington <[email protected]> * fix: adjust OAS v3.1 link #439 (comment) * chore: make github docs links less english-centric * docs: update title/description per feedback from Spang * chore: reduce number of unnecessary links * docs: troubleshooting docs * chore: shorten title juuuust a lil bit * feat: add node.js version find/replace * docs: first pass at CI environments stuff Let's hope this works... * chore: rename steps * chore: add comment, try reformatting * chore: fix code block formatting well... this is annoying as hell * ci(docs): restore on step so it only runs on `main` * Update src/lib/getNodeVersion.js Co-authored-by: Jon Ursenbach <[email protected]> Co-authored-by: Jon Ursenbach <[email protected]> Co-authored-by: Ryan Park <[email protected]> Co-authored-by: Ellie Rossuck <[email protected]> Co-authored-by: Jon Ursenbach <[email protected]> Co-authored-by: Dom Harrington <[email protected]>
readmeio · Mar 1, 2022 · 3803172 · 3803172
1 parent e1745bc
commit 3803172
Show file tree

Hide file tree

Showing 7 changed files with 409 additions and 13 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,54 @@
+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/[email protected]
+
+      # 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 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 few find/replaces!
+      - name: Find and replace Node.js version placeholders
+        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 `rdme` version placeholders
+        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
+        # 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
diff --git 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 [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/oas/v3.1.0.html) 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
 
-### 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 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
+npm install rdme --save-dev
 ```
 
+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]
+```
+
+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
 
-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
@@ -30,12 +44,41 @@ If you wish to get more information about any command within `rdme`, you can exe
 
 ### Common `rdme` Options
 
-- `--key <string>`: 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 <string>`: Your project version.
+- `--key <string>`: 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 <string>`: Your project version. See [our docs](https://docs.readme.com/docs/versions) for more information.
+
+### 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:
+
+```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
+```
+
+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
 
-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.
 
@@ -59,16 +102,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`.
@@ -97,6 +136,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}
 ```

diff --git a/__tests__/lib/getNodeVersion.test.js 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
@@ -0,0 +1,14 @@
+#! /usr/bin/env node
+
+const getNodeVersion = require('../src/lib/getNodeVersion');
+const pkg = require('../package.json');
+
+const name1 = 'RDME_VERSION';
+const name2 = 'NODE_VERSION';
+
+/**
+ * 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=${name1}::${pkg.version}`); // eslint-disable-line no-console
+console.log(`::set-output name=${name2}::${getNodeVersion()}`); // eslint-disable-line no-console