From 50218f38645e022bd371b4e6c2bb11b7ed26acb7 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 11 Oct 2022 15:12:54 -0500 Subject: [PATCH 01/34] docs: updated setup/auth instructions --- README.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index cb4a37332..4036b9122 100644 --- a/README.md +++ b/README.md @@ -16,13 +16,15 @@ > **Note** > 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: +#### Installing `rdme` to a Project + +The recommended approach for shared projects is to install `rdme` in your project's dependencies. That way you don't run into unexpected behavior with mismatching versions of `rdme`. 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 ``` -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: +Once installed in your project, you can use the `npx` prefix (which is included if you have `npm` installed) to run your CLI commands locally. For example: ```sh npx rdme openapi:validate [file] @@ -30,17 +32,23 @@ npx rdme openapi: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 - -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). +#### Installing `rdme` to Your Local Machine -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. +The simplest way to use `rdme` is to install it globally: ```sh -rdme login +npm install -g rdme ``` -`rdme whoami` is also available to you to determine who you are logged in as, and to what project, as well as `rdme logout` for logging out of that account. +With a global installation, you'll be able to run `rdme` within any directory on your local machine. If you log in once, you can quickly access your project without having to remember your API key (see the [Authentication](#authentication) section below). + +### Authentication + +For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing a 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 using `rdme login`. Once you follow the prompts and are successfully authenticated, your API key will be saved to a local configuration file (`~/.config/configstore/rdme-production.json`) and you won't have to provide the `--key` option to commands that require it. + +`rdme whoami` is also available to you to determine who is logged in, and to what project. You can clear your stored credentials with `rdme logout`. ## Usage From 7fb8a95e6b5e59be82ab4f2d384dcf746ee0367a Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 12 Oct 2022 16:07:38 -0500 Subject: [PATCH 02/34] chore: drop v8 callout --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 4036b9122..59a2a7d17 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,3 @@ -> **Note** -> These docs are for [the forthcoming `v8` release](https://github.com/readmeio/rdme/milestone/3). You can view the docs for the current release (`v7.5.0`) [here](https://github.com/readmeio/rdme/tree/7.5.0#readme). - # πŸ“– rdme [![](https://d3vv6lp55qjaqc.cloudfront.net/items/1M3C3j0I0s0j3T362344/Untitled-2.png)](https://readme.com) From dbf2b2e01f636d5b2c75ef853fe1422873c2e7c0 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 12 Oct 2022 16:28:14 -0500 Subject: [PATCH 03/34] docs: first pass at content reorg --- README.md | 12 +- documentation/github-actions-docs-example.md | 51 +++++ .../github-actions-openapi-example.md | 99 +++++++++ documentation/rdme.md | 188 ++++++------------ 4 files changed, 213 insertions(+), 137 deletions(-) create mode 100644 documentation/github-actions-docs-example.md create mode 100644 documentation/github-actions-openapi-example.md diff --git a/README.md b/README.md index 59a2a7d17..480c64488 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ The Markdown files will require YAML front matter with certain ReadMe documentat Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. ```sh -rdme docs path-to-markdown-files --version={project-version} +rdme docs [path-to-directory-of-markdown] --version={project-version} ``` This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode). @@ -225,7 +225,7 @@ rdme docs:edit --version={project-version} #### Syncing a Single Markdown File to ReadMe ```sh -rdme docs:single path-to-markdown-file --version={project-version} +rdme docs:single [path-to-file.md] --version={project-version} ``` ### Changelogs @@ -237,7 +237,7 @@ The Markdown files will require YAML front matter with certain ReadMe documentat Passing in a path to a directory will also sync any Markdown files that are located in subdirectories. ```sh -rdme changelogs path-to-markdown-files +rdme changelogs [path-to-directory-of-markdown] ``` This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode). @@ -245,7 +245,7 @@ This command also has a dry run mode, which can be useful for initial setup and #### Syncing a Single Markdown File to ReadMe ```sh -rdme changelogs:single path-to-markdown-file +rdme changelogs:single [path-to-file.md] ``` ### Custom Pages @@ -257,7 +257,7 @@ Custom Pages has support for both Markdown and HTML files. These files will requ Passing in a path to a directory will also sync any HTML/Markdown files that are located in subdirectories. ```sh -rdme custompages path-to-markdown-files +rdme custompages [path-to-directory-of-markdown] ``` This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode). @@ -265,7 +265,7 @@ This command also has a dry run mode, which can be useful for initial setup and #### Syncing a Single Custom Page to ReadMe ```sh -rdme custompages:single path-to-markdown-file +rdme custompages:single [path-to-file.md] ``` ### Versions diff --git a/documentation/github-actions-docs-example.md b/documentation/github-actions-docs-example.md new file mode 100644 index 000000000..4cc586d2f --- /dev/null +++ b/documentation/github-actions-docs-example.md @@ -0,0 +1,51 @@ +--- +title: 'GitHub Action Example: Syncing Markdown' +category: 5f7ce9e3a5504d0414d024c2 +--- + +Do you have Markdown files stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync them to ReadMe every time they're updated in GitHub. Let's go over how to set this up! + +## "Automagical" Workflow File Generation πŸͺ„ + +To set up a GitHub Actions workflow for syncing a directory of Markdown docs, the fastest and easiest way to do so is by running the following command on your local machine: + +```sh +rdme docs [path-to-directory-of-markdown] --github +``` + +This will scan the directory for Markdown files, sync them to ReadMe, and then create your GitHub Actions workflow file. Once that's done, create your [repository secret](url), push your workflow file to GitHub, and get syncing! 🎊 + +## Constructing a GitHub Actions Workflow File By Hand πŸ”¨ + +> 🚧 Wait β€” there’s an easier way to do this! +> +> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation-πŸͺ„). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing. + +In order to construct the file by hand, you'll first want to grab a project version to ensure that your docs sync to the right place in your developer hub. That version will be passed via the `--version` flag. See below for a full example: + +```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@v3 + + # Run GitHub Action to sync docs in `documentation` directory + - 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 + uses: readmeio/rdme@RDME_VERSION + with: + rdme: docs ./documentation --key=${{ secrets.README_API_KEY }} --version=2.0 +``` + +In the example above, every push to the `main` branch will sync the Markdown contents of the `documentation` directory to version 2.0 of your ReadMe project. diff --git a/documentation/github-actions-openapi-example.md b/documentation/github-actions-openapi-example.md new file mode 100644 index 000000000..1dc914b3b --- /dev/null +++ b/documentation/github-actions-openapi-example.md @@ -0,0 +1,99 @@ +--- +title: 'GitHub Action Example: Syncing OpenAPI' +category: 5f7ce9e3a5504d0414d024c2 +--- + +Is your OpenAPI definition stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync it to ReadMe every time it's updated in GitHub. Let's go over how to set this up! + +## "Automagical" Workflow File Generation πŸͺ„ + +To set up a GitHub Actions workflow for syncing an OpenAPI or Swagger definition, the fastest and easiest way to do so is by running the following command on your local machine: + +```sh +rdme openapi --github +``` + +This will locate your OpenAPI definition, sync it to ReadMe, and then create your GitHub Actions workflow file. Once that's done, create your [repository secret](url), push your workflow file to GitHub, and get syncing! 🎊 + +## Constructing a GitHub Actions Workflow File By Hand πŸ”¨ + +> 🚧 Wait β€” there’s an easier way to do this! +> +> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation-πŸͺ„). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing. + +In order to construct the file by hand, 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 definition, run the following: + + rdme openapi [path-to-file.json] --key= --id=API_DEFINITION_ID +``` + +
+ +We have a walkthrough video available which goes over the whole end-to-end process of obtaining the API definition ID and constructing the GitHub Actions workflow file: + + + +[block:html] +{ +"html": "
" +} +[/block] + +Once you've obtained your API definition ID (let's call it `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@v3 + + # 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 + uses: readmeio/rdme@RDME_VERSION + with: + rdme: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID +``` + +In the example above, every push to the `main` branch will sync the OpenAPI file located at `./path-to-file.json` to the API specification `API_DEFINITION_ID` in your ReadMe project. diff --git a/documentation/rdme.md b/documentation/rdme.md index a9f011c41..bb6104550 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -81,9 +81,9 @@ You can also specify several other page attributes in your YAML front matter, su If you're setting up new pages or if you're generally unsure if you've set up your page attributes correctly, each command has a dry run mode. This will allow you preview the changes without actually creating/updating any docs in ReadMe, which can be extremely useful for initial setup (oh, and we have [comprehensive debugging options](#troubleshooting) available as well!). To enable dry run mode, use the `--dryRun` flag: ```sh -rdme docs path-to-markdown-files --version={project-version} --dryRun -rdme changelogs path-to-markdown-files --dryRun -rdme custompages path-to-markdown-files --dryRun +rdme docs [path-to-directory-of-markdown] --version={project-version} --dryRun +rdme changelogs [path-to-directory-of-markdown] --dryRun +rdme custompages [path-to-directory-of-markdown] --dryRun ``` The command output will indicate whether each page is being created or updated alongside all processed page attributes. @@ -98,163 +98,89 @@ While there are [dozens of event options available](https://docs.github.com/acti > > 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, 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: +The fastest way to create a GitHub Actions workflow file is by doing the following: -```yml -- uses: actions/checkout@v3 -- uses: readmeio/rdme@RDME_VERSION - with: - rdme: [your command here] -``` - -The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command: +1. Download `rdme` to your local machine (see [our setup instructions](https://github.com/readmeio/rdme#setup)) +2. Open your command line at the root of your GitHub repository +3. Run the command you wish to automate on your local machine with the `--github` flag tacked on at the end. For example: ```sh -rdme openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID +rdme openapi --github ``` -To execute this command via GitHub Actions, the step would look like this: - -```yml -- uses: readmeio/rdme@RDME_VERSION - with: - rdme: openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID -``` - -We'll dive into several full GitHub Workflow file examples (including a video demo) below! - -### Example: Syncing an OpenAPI Definition +This will run through the command, ask you a few quick questions, and then automatically generate a GitHub Actions workflow file for you πŸͺ„ - - -[block:html] -{ -"html": "
" -} -[/block] - -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: +If you don't include the `--github` flag but the CLI detects that you are in a GitHub repository, we'll ask if you'd like to set up the GitHub Action. If you answer "no", we won't ask you again for that major version of `rdme` (i.e., if you decline to set up a GitHub Actions workflow for version 8 of `rdme`, we won't ask again until you've upgraded to version 9 or above). -```sh -rdme openapi [path-to-file.json] -``` +> πŸ‘ Did you know? +> +> 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 the relevant files on GitHub: +> +> - [The Markdown source file for the page you're reading](https://github.com/readmeio/rdme/blob/main/documentation/rdme.md) πŸ“œ +> - [The GitHub Actions workflow file that syncs the Markdown 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) βœ… -Once you follow the prompts and upload your OpenAPI definition, you'll receive a confirmation message that looks something like this: +### Securely Using Your API Key -``` -You've successfully updated an OpenAPI file on your ReadMe project! - - http://dash.readme.com/project/{your_project}/v1.0/refs/pet +> 🚧 Secretly store your ReadMe API Key! +> +> GitHub Actions has [secrets](https://docs.github.com/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 and 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/actions/security-guides/encrypted-secrets). -To update your OpenAPI definition, run the following: +To use sensitive information (like your ReadMe API key) in your `rdme` GitHub Action, first [create a new repository secret](https://docs.github.com/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: - rdme openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID +```yml +- uses: readmeio/rdme@RDME_VERSION + with: + rdme: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID ``` -
+
Manually Creating a GitHub Actions Workflow File -Once you've obtained your API definition ID, your full GitHub Workflow file will look something like this: +If you need to manually set up a workflow, create a new [GitHub Actions workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository (or use an existing workflow file) and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: ```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@v3 - - # 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 - uses: readmeio/rdme@RDME_VERSION - with: - rdme: openapi [path-to-file.json] --key=<> --id=API_DEFINITION_ID +- uses: actions/checkout@v3 +- uses: readmeio/rdme@RDME_VERSION + with: + rdme: [your command here] ``` -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: 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 the relevant files on GitHub: +The command syntax in GitHub Actions is functionally equivalent to the CLI. For example, take the following CLI command: -- [The Markdown source file for the page you're reading](https://github.com/readmeio/rdme/blob/main/documentation/rdme.md) πŸ“œ -- [The GitHub Actions workflow file that syncs the Markdown 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) βœ… +```sh +rdme validate [path-to-file.json] +``` -To recreate this magic in your repository, your GitHub Workflow file will look something like this: +To execute this command via GitHub Actions, the step would 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@v3 - - # Run GitHub Action to sync docs in `documentation` directory - - 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 - uses: readmeio/rdme@RDME_VERSION - with: - rdme: docs ./documentation --key=<> --version=2.0 +- uses: readmeio/rdme@RDME_VERSION + with: + rdme: validate [path-to-file.json] ``` -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: Using GitHub Secrets +### GitHub Actions Examples -> 🚧 Secretly store your ReadMe API Key! -> -> GitHub Actions has [secrets](https://docs.github.com/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/actions/security-guides/encrypted-secrets). +Want to start syncing? We have several example workflow files available: -To use a GitHub secret in your `rdme` GitHub Action, first [create a new repository secret](https://docs.github.com/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@RDME_VERSION - with: - rdme: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=${{ secrets.README_API_DEFINITION_ID }} -``` +- [Syncing an OpenAPI definition](https://docs.readme.com/docs/github-actions-openapi-example) +- [Syncing a directory of Markdown files](https://docs.readme.com/docs/github-actions-docs-example) ## 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 rdme@RDME_VERSION` in a Node.js environment. See below for several examples. +> 🚧 Secretly store your ReadMe API Key! +> +> Nearly every CI service has a way to securely add secrets so that they're not exposed in your scripts and build logs. We strongly recommend using such a feature for storing your ReadMe API key. The following examples use `$README_API_KEY`, which is how you typically load such variables in your scripts. We've included some links below on how to configure these for the respective examples: +> +> - [Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Secured-variables) +> - [GitLab CI](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project) + @@ -305,7 +231,7 @@ If you're troubleshooting issues in a GitHub Actions environment, you can enable > 🚧 Debug Logs May Contain Sensitive Information > -> Enabling step debug logs will produce comprehensive logging for **all** of your GitHub Actions 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. +> Enabling step debug logs will produce comprehensive logging for **all** of your GitHub Actions workflow steps. While GitHub automatically masks any sensitive information you load in with [secrets](#securely-using-your-api-key), 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. > From ec2cba33a6a5cbeee2d9af6b6aafe8b8dcc67ffd Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 12 Oct 2022 16:42:46 -0500 Subject: [PATCH 04/34] chore: link fixes, more cleanup and language alignment --- README.md | 23 ++++------------------- documentation/legacy-github-action.md | 2 +- documentation/rdme.md | 2 +- 3 files changed, 6 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 480c64488..fc24c19eb 100644 --- a/README.md +++ b/README.md @@ -61,30 +61,15 @@ If you wish to get more information about any command within `rdme`, you can exe > **Note** > For a full GitHub Workflow file example and additional information on GitHub Actions usage, check out [our docs](https://docs.readme.com/docs/rdme#github-actions-usage). -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@v3 -- 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: +For usage in [GitHub Actions](https://docs.github.com/actions), you can create a new GitHub Actions workflow file by including the `--github` flag with the command you wish to run in GitHub Actions. For example: ```sh -rdme openapi [path-to-file.json] --key=API_KEY --id=API_DEFINITION_ID +rdme openapi --github ``` -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 -``` +This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you πŸͺ„ -Note that the `@XX` in the above examples refers to the version of `rdme`. You can see examples featuring the latest version in [our docs](https://docs.readme.com/docs/rdme#example-syncing-an-openapi-definition). We recommend pointing to a fixed version, as opposed to pointing to something like the `main` branch, which could unexpectedly break your workflows. We also 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). +You can see examples featuring the latest version in [our docs](https://docs.readme.com/docs/rdme#github-actions-examples). 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 diff --git a/documentation/legacy-github-action.md b/documentation/legacy-github-action.md index 568103020..47888a9ff 100644 --- a/documentation/legacy-github-action.md +++ b/documentation/legacy-github-action.md @@ -45,7 +45,7 @@ There are a few 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. `@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. -3. If you used secrets to encrypt the `readme-oas-key` value, you'll have to split this value out into two separate secretsβ€”one for the API key and one for the API definition ID. You can see an example of this [here](https://docs.readme.com/docs/rdme#example-using-github-secrets). +3. If you used secrets to encrypt the `readme-oas-key` value, you'll have to split this value out into two separate secretsβ€”one for the API key and one for the API definition ID. You can see an example of this [here](https://docs.readme.com/docs/github-actions-openapi-example).
diff --git a/documentation/rdme.md b/documentation/rdme.md index bb6104550..e97a44d76 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -108,7 +108,7 @@ The fastest way to create a GitHub Actions workflow file is by doing the followi rdme openapi --github ``` -This will run through the command, ask you a few quick questions, and then automatically generate a GitHub Actions workflow file for you πŸͺ„ +This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you πŸͺ„ If you don't include the `--github` flag but the CLI detects that you are in a GitHub repository, we'll ask if you'd like to set up the GitHub Action. If you answer "no", we won't ask you again for that major version of `rdme` (i.e., if you decline to set up a GitHub Actions workflow for version 8 of `rdme`, we won't ask again until you've upgraded to version 9 or above). From 05d2be0cc5320b825be73b74bcebaa20cf15613a Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 12 Oct 2022 18:25:58 -0500 Subject: [PATCH 05/34] docs: update cover image MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit s/o @jaclynchao πŸ₯³ --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fc24c19eb..9a404ae66 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # πŸ“– rdme -[![](https://d3vv6lp55qjaqc.cloudfront.net/items/1M3C3j0I0s0j3T362344/Untitled-2.png)](https://readme.com) +[![](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com) [![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) From ca80b32605f9da5451008b858aca0e508a402bae Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 13 Oct 2022 10:07:14 -0500 Subject: [PATCH 06/34] chore: remove heading, add alt text Co-Authored-By: Jon Ursenbach --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 9a404ae66..094c50155 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,4 @@ -# πŸ“– rdme - -[![](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com) +[![rdme](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com) [![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) From bc5d97ee6f7caabbfab5bbbc00de0adf98b06ecb Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 13 Oct 2022 10:20:33 -0500 Subject: [PATCH 07/34] chore: fix a few duplicated headers --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 094c50155..eb91ca8fd 100644 --- a/README.md +++ b/README.md @@ -225,7 +225,7 @@ rdme changelogs [path-to-directory-of-markdown] This command also has a dry run mode, which can be useful for initial setup and debugging. You can read more about dry run mode [in our docs](https://docs.readme.com/docs/rdme#dry-run-mode). -#### Syncing a Single Markdown File to ReadMe +#### Syncing a Single Changelog to ReadMe ```sh rdme changelogs:single [path-to-file.md] @@ -273,8 +273,6 @@ If you wish to see the raw JSON output from our API in this response, supply the rdme versions:create ``` -##### Create a New Version - If you wish to automate the process of creating a new project version, and not have the CLI prompt you for input, you can do so by supplying the necessary flags to `versions:create`. For example: From 92a0c09c5108b2112ffea056c79eb4788290fe69 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 13 Oct 2022 10:53:16 -0500 Subject: [PATCH 08/34] docs: rework headers --- README.md | 15 ++++++++++++--- documentation/rdme.md | 15 +++++++++++++-- 2 files changed, 25 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index eb91ca8fd..1b3d48cf8 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,17 @@ [![rdme](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com) -[![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 [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. +

+ ReadMe's official command-line interface (CLI) and GitHub Action. +

+ +

+ NPM Version + Node Version + MIT License + Build status +

+ +With `rdme`, you can manage your [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html) (or [Swagger](https://swagger.io/specification/v2/)) definition and sync it to your API reference docs 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 ReadMe project and managing project versions. ## Configuration diff --git a/documentation/rdme.md b/documentation/rdme.md index e97a44d76..c734cadad 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -17,9 +17,20 @@ Check out `.github/workflows/docs.yml` for more info on this! --> -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! +[![rdme](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com) + +

+ 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) +

+ NPM Version + Node Version + MIT License + Build status +

+ +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! With `rdme`, you can create workflows for a variety of use cases, including: From f76b79793500ae6ee8e063a703f08d8096641f2c Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 13 Oct 2022 10:54:17 -0500 Subject: [PATCH 09/34] docs(openapi): update heading hierarchy, content updates --- README.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1b3d48cf8..55b69b5f7 100644 --- a/README.md +++ b/README.md @@ -80,16 +80,24 @@ You can see examples featuring the latest version in [our docs](https://docs.rea ### OpenAPI / Swagger -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). +With `rdme`, you have access to a variety of tools to manage your OpenAPI or Swagger definition, most of which don't require an account on ReadMe. These tools include: + +- [Reduction](#reducing-an-api-definition) πŸ“‰ +- [Syncing](#syncing-an-api-definition-to-readme) πŸ¦‰ +- [Validation](#validating-an-api-definition) βœ… + +`rdme` 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 `rdme` supports API Definitions that are written in either JSON or YAML. +#### Syncing an API Definition to ReadMe + > **Note** > The `rdme openapi` command supports both OpenAPI and Swagger API definitions. The `rdme swagger` command is an alias for `rdme openapi` and is deprecated. If you wish to see the raw JSON output of any of the `openapi` command examples below, supply the `--raw` flag. -#### Uploading a New API Definition to ReadMe +##### Uploading a New API Definition to ReadMe This will upload `path-to-openapi.json` to your project and return an ID and URL for you to later update your file, and view it in the client. @@ -105,7 +113,7 @@ rdme openapi [path-to-file.json] --version={project-version} --create This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag. -#### Editing (Re-Syncing) an Existing API Definition +##### Editing (Re-Syncing) an Existing API Definition This will edit (re-sync) an existing API definition (identified by `--id`) within your ReadMe project. **This is the recommended approach for usage in CI environments.** @@ -113,7 +121,7 @@ This will edit (re-sync) an existing API definition (identified by `--id`) withi rdme openapi [path-to-file.json] --id={existing-id} ``` -#### Uploading or Editing an API Definition in a Project Version +##### Uploading or Editing an API Definition in a Project Version You can additionally 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. @@ -145,7 +153,7 @@ rdme openapi [path-to-file.json] --version={project-version} --update This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag. -#### Omitting the File Path +##### Omitting the File Path If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. `rdme` will then look for JSON or YAML files (including in sub-directories) that contain a top-level [`openapi`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields) or [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#fixed-fields) property. @@ -162,7 +170,7 @@ If you run `rdme` within a directory that contains your OpenAPI or Swagger defin rdme openapi ``` -#### Override the Working Directory +##### Override the Working Directory By default, `rdme` bundles all [references](https://swagger.io/docs/specification/using-ref/) with paths based on the directory that `rdme` is being run in. You can override the working directory using the `--workingDirectory` option, which can be helpful for bundling certain external references (see [here](__tests__/__fixtures__/relative-ref-oas/petstore.json) for an example file). @@ -172,7 +180,7 @@ rdme openapi petstore.json --workingDirectory=[path to directory] #### Validating an API Definition -You can also perform a local validation of your API definition without uploading it to ReadMe, which can be useful when constructing or editing your API definition. +You can also perform a local validation of your API definition (no ReadMe account required!), which can be useful when constructing or editing your API definition. ```sh rdme openapi:validate [path-to-file.json] From 3778676c6b19de71fc9c9d2747e33b325431738b Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 14 Oct 2022 10:30:26 -0500 Subject: [PATCH 10/34] chore: c'mon dude --- CONTRIBUTING.md | 2 +- documentation/rdme.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7f76a345..2f6aa1125 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,7 +40,7 @@ Once you've installed `act`, it'll ask you what Docker image size you'd like. Th -P ubuntu-18.04=ghcr.io/catthehacker/ubuntu:act-18.04 ``` -Our GitHub Actions guidance states that Action workflows should have a [`runs-on` value](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) of `ubuntu-latest`. These runners are updated frequently β€” you can find links to the the latest versions by navigating [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software) and selecting the latest Ubuntu link. Because of this, you'll want to make sure your `ghcr.io/catthehacker/ubuntu` image stays up-to-date by doing a periodic pull: +Our GitHub Actions guidance states that Action workflows should have a [`runs-on` value](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) of `ubuntu-latest`. These runners are updated frequently β€” you can find links to the latest versions by navigating [here](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software) and selecting the latest Ubuntu link. Because of this, you'll want to make sure your `ghcr.io/catthehacker/ubuntu` image stays up-to-date by doing a periodic pull: ```sh docker pull ghcr.io/catthehacker/ubuntu:act-latest diff --git a/documentation/rdme.md b/documentation/rdme.md index c734cadad..64a66b6d8 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -137,7 +137,7 @@ If you don't include the `--github` flag but the CLI detects that you are in a G > 🚧 Secretly store your ReadMe API Key! > -> GitHub Actions has [secrets](https://docs.github.com/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 and 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/actions/security-guides/encrypted-secrets). +> GitHub Actions has [secrets](https://docs.github.com/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 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/actions/security-guides/encrypted-secrets). To use sensitive information (like your ReadMe API key) in your `rdme` GitHub Action, first [create a new repository secret](https://docs.github.com/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: From 487431ac7c24d0a84f146e465f14d6ab6b588605 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 14 Oct 2022 12:23:04 -0500 Subject: [PATCH 11/34] docs(openapi): content reorg, better intro --- README.md | 40 ++++++++++++++++++---------------------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 55b69b5f7..cadfeeaa1 100644 --- a/README.md +++ b/README.md @@ -92,10 +92,27 @@ The following examples use JSON files, but `rdme` supports API Definitions that #### Syncing an API Definition to ReadMe +`rdme openapi` locates your API definition (if [you don't supply one](#omitting-the-file-path)), validates it, and then syncs it to your API reference on ReadMe. + > **Note** > The `rdme openapi` command supports both OpenAPI and Swagger API definitions. The `rdme swagger` command is an alias for `rdme openapi` and is deprecated. -If you wish to see the raw JSON output of any of the `openapi` command examples below, supply the `--raw` flag. +If you wish to programmatically access any of this script's results (such as the API defintion ID or the link to the corresponding docs in your dashboard), supply the `--raw` flag and the command will return a JSON output. + +This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag. + +##### Omitting the File Path + +If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. `rdme` will then look for JSON or YAML files (including in sub-directories) that contain a top-level [`openapi`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields) or [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#fixed-fields) property. + +> **Note** `rdme` will not scan anything in the following: +> +> - Any `.git/` directories (if they exist) +> - Any files/directories specified in `.gitignore` files (including any `.gitignore` files in subdirectories, if they exist) + +```sh +rdme openapi +``` ##### Uploading a New API Definition to ReadMe @@ -111,8 +128,6 @@ If you want to bypass the prompt to create or update an API definition, you can rdme openapi [path-to-file.json] --version={project-version} --create ``` -This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag. - ##### Editing (Re-Syncing) an Existing API Definition This will edit (re-sync) an existing API definition (identified by `--id`) within your ReadMe project. **This is the recommended approach for usage in CI environments.** @@ -151,25 +166,6 @@ You can add `--update` to the command so if there's only one API definition for rdme openapi [path-to-file.json] --version={project-version} --update ``` -This command also has a dry run mode, which can be useful for initial setup and debugging. You can perform a dry run by supplying the `--dryRun` flag. - -##### Omitting the File Path - -If you run `rdme` within a directory that contains your OpenAPI or Swagger definition, you can omit the file path. `rdme` will then look for JSON or YAML files (including in sub-directories) that contain a top-level [`openapi`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#fixed-fields) or [`swagger`](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#fixed-fields) property. - - - -> **Note** -> `rdme` will not scan anything in the following: -> -> - Any `.git/` directories (if they exist) -> - Any files/directories specified in `.gitignore` files (including any `.gitignore` files in subdirectories, if they exist) - - -```sh -rdme openapi -``` - ##### Override the Working Directory By default, `rdme` bundles all [references](https://swagger.io/docs/specification/using-ref/) with paths based on the directory that `rdme` is being run in. You can override the working directory using the `--workingDirectory` option, which can be helpful for bundling certain external references (see [here](__tests__/__fixtures__/relative-ref-oas/petstore.json) for an example file). From c17e44669e692e4e501d52cdd569b8f7239dc0b3 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 14 Oct 2022 13:10:42 -0500 Subject: [PATCH 12/34] docs(GHA): cleanup --- documentation/rdme.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index 64a66b6d8..195fd08b7 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -109,6 +109,8 @@ While there are [dozens of event options available](https://docs.github.com/acti > > 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). +### GitHub Actions Quick Start + The fastest way to create a GitHub Actions workflow file is by doing the following: 1. Download `rdme` to your local machine (see [our setup instructions](https://github.com/readmeio/rdme#setup)) @@ -121,8 +123,6 @@ rdme openapi --github This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you πŸͺ„ -If you don't include the `--github` flag but the CLI detects that you are in a GitHub repository, we'll ask if you'd like to set up the GitHub Action. If you answer "no", we won't ask you again for that major version of `rdme` (i.e., if you decline to set up a GitHub Actions workflow for version 8 of `rdme`, we won't ask again until you've upgraded to version 9 or above). - > πŸ‘ Did you know? > > 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 🀯 @@ -147,12 +147,21 @@ To use sensitive information (like your ReadMe API key) in your `rdme` GitHub Ac rdme: openapi [path-to-file.json] --key=${{ secrets.README_API_KEY }} --id=API_DEFINITION_ID ``` -
Manually Creating a GitHub Actions Workflow File +### Manually Configuring a GitHub Actions Workflow + +We recommend using the [quick start](#github-actions-quick-start) to get started with GitHub Actions. But if you are familiar with the [workflow syntax](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) and wish to manually configure a workflow, follow these steps: -If you need to manually set up a workflow, create a new [GitHub Actions workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository (or use an existing workflow file) and add the following [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: +1. Create a new [GitHub Actions workflow file](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions) in the `.github/workflows` directory of your repository (or use an existing workflow file) + +1. Configure the [`on`](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#on) property, which determines what triggers the execution of the workflow. + +1. Add the following two [steps](https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idsteps) to your workflow: ```yml +# Required in order for the GitHub Action to access your repo's contents - uses: actions/checkout@v3 + +# Runs the `rdme` command on your repo's contents - uses: readmeio/rdme@RDME_VERSION with: rdme: [your command here] @@ -172,7 +181,7 @@ To execute this command via GitHub Actions, the step would look like this: rdme: validate [path-to-file.json] ``` -
+The following section has links to full GitHub Actions workflow file examples. ### GitHub Actions Examples From fc7eb5d28bb32eefe0c2db84778908f71d499438 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 18 Oct 2022 09:36:52 -0500 Subject: [PATCH 13/34] chore: update comments --- .github/workflows/docs.yml | 2 +- documentation/github-actions-docs-example.md | 13 +++++++++++++ documentation/github-actions-openapi-example.md | 12 ++++++++++++ documentation/rdme.md | 3 +-- 4 files changed, 27 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index a8de1f700..52037bece 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -57,7 +57,7 @@ jobs: if: github.event_name == 'push' && github.event.ref == 'refs/heads/main' # 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 + # We recommend specifying a fixed version, i.e. @8.0.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/github-actions-docs-example.md b/documentation/github-actions-docs-example.md index 4cc586d2f..65ec6ca27 100644 --- a/documentation/github-actions-docs-example.md +++ b/documentation/github-actions-docs-example.md @@ -3,6 +3,19 @@ title: 'GitHub Action Example: Syncing Markdown' category: 5f7ce9e3a5504d0414d024c2 --- + + Do you have Markdown files stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync them to ReadMe every time they're updated in GitHub. Let's go over how to set this up! ## "Automagical" Workflow File Generation πŸͺ„ diff --git a/documentation/github-actions-openapi-example.md b/documentation/github-actions-openapi-example.md index 1dc914b3b..f2f6a5d8a 100644 --- a/documentation/github-actions-openapi-example.md +++ b/documentation/github-actions-openapi-example.md @@ -3,6 +3,18 @@ title: 'GitHub Action Example: Syncing OpenAPI' category: 5f7ce9e3a5504d0414d024c2 --- + + Is your OpenAPI definition stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync it to ReadMe every time it's updated in GitHub. Let's go over how to set this up! ## "Automagical" Workflow File Generation πŸͺ„ diff --git a/documentation/rdme.md b/documentation/rdme.md index 195fd08b7..2fef98d45 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -8,8 +8,7 @@ category: 5f7ce9e3a5504d0414d024c2 Hello curious raw Markdown reader! πŸ‘‹ 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 +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. From 2df9a2bd5295aa958c296ccbc86118d58ef71dc3 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 18 Oct 2022 10:41:20 -0500 Subject: [PATCH 14/34] docs: add CircleCI + Travis examples CircleCI code sample source: https://circleci.com/blog/next-testing/ CircleCI config reference: https://circleci.com/docs/configuration-reference/ Travis CI lifecycle reference: https://docs.travis-ci.com/user/job-lifecycle/ Travis CI Node.js reference: https://docs.travis-ci.com/user/languages/javascript-with-nodejs/#specifying-nodejs-versions Co-Authored-By: Ryan Park --- documentation/rdme.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/documentation/rdme.md b/documentation/rdme.md index 2fef98d45..1fb9c211c 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -198,7 +198,9 @@ Since `rdme` is a command-line tool at its core, you can use `rdme` to sync your > Nearly every CI service has a way to securely add secrets so that they're not exposed in your scripts and build logs. We strongly recommend using such a feature for storing your ReadMe API key. The following examples use `$README_API_KEY`, which is how you typically load such variables in your scripts. We've included some links below on how to configure these for the respective examples: > > - [Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Secured-variables) +> - [CircleCI](https://circleci.com/docs/env-vars/) > - [GitLab CI](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project) +> - [Travis CI](https://docs.travis-ci.com/user/environment-variables) +If you notice any issues with any of these examples, please open up an issue on [the `rdme` repository on GitHub](https://github.com/readmeio/rdme). + ## 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 6c09206639f906f00132d53a63e3770373a89f56 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 18 Oct 2022 11:17:55 -0500 Subject: [PATCH 15/34] docs: add setup language on node.js also rearranged the installation steps so global installation is first Co-Authored-By: Ryan Park --- README.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index cadfeeaa1..39f5af8cb 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,20 @@ With `rdme`, you can manage your [OpenAPI](https://spec.openapis.org/oas/v3.1.0. > **Note** > These setup instructions are for CLI usage only. For usage in GitHub Actions, see [GitHub Actions](#github-actions) below. +Node Version + +To install the `rdme` CLI, you'll need to have [Node.js](https://nodejs.org) installed. Node.js comes bundled with [the `npm` CLI](https://github.com/npm/cli), which you'll need to install `rdme`. You can see our current Node.js version requirements in the green badge on the right. + +#### Installing `rdme` to Your Local Machine + +The simplest way to use `rdme` is to install it globally: + +```sh +npm install -g rdme +``` + +With a global installation, you'll be able to run `rdme` within any directory on your local machine. If you log in once, you can quickly access your project without having to remember your API key (see the [Authentication](#authentication) section below). + #### Installing `rdme` to a Project The recommended approach for shared projects is to install `rdme` in your project's dependencies. That way you don't run into unexpected behavior with mismatching versions of `rdme`. 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: @@ -36,16 +50,6 @@ npx rdme openapi: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. -#### Installing `rdme` to Your Local Machine - -The simplest way to use `rdme` is to install it globally: - -```sh -npm install -g rdme -``` - -With a global installation, you'll be able to run `rdme` within any directory on your local machine. If you log in once, you can quickly access your project without having to remember your API key (see the [Authentication](#authentication) section below). - ### Authentication For usage in CI environments (GitHub Actions, CircleCI, Travis CI, etc.) or if you're working with multiple ReadMe projects, we recommend providing a project API key via the `--key` option (instead of the configuration file authentication described below). From 38c0695f3db57d03c29a84260f1183904c69b6fc Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 18 Oct 2022 12:17:15 -0500 Subject: [PATCH 16/34] docs: periods Co-Authored-By: Jon Ursenbach --- README.md | 2 +- documentation/rdme.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 39f5af8cb..f2a510826 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ For usage in [GitHub Actions](https://docs.github.com/actions), you can create a rdme openapi --github ``` -This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you πŸͺ„ +This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you. πŸͺ„ You can see examples featuring the latest version in [our docs](https://docs.readme.com/docs/rdme#github-actions-examples). 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 1fb9c211c..772a3f9d2 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -120,7 +120,7 @@ The fastest way to create a GitHub Actions workflow file is by doing the followi rdme openapi --github ``` -This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you πŸͺ„ +This will run through the `openapi` command, ask you a few quick questions, and then automatically create a fully functional GitHub Actions workflow file for you. πŸͺ„ > πŸ‘ Did you know? > From 8cff5a4306a4d28caf7950a1dea802cf21818e03 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 18 Oct 2022 12:17:27 -0500 Subject: [PATCH 17/34] docs: sentence flow fix Co-Authored-By: Jon Ursenbach --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f2a510826..224bf7ccc 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ With a global installation, you'll be able to run `rdme` within any directory on #### Installing `rdme` to a Project -The recommended approach for shared projects is to install `rdme` in your project's dependencies. That way you don't run into unexpected behavior with mismatching versions of `rdme`. 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: +The recommended approach for shared projects is to install `rdme` in your project's dependencies, that way you don't run into unexpected behavior with mismatching versions of `rdme`. 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 462c7b04b4ddd364e0cb457d87ce06cf153d64fe Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 18 Oct 2022 12:23:05 -0500 Subject: [PATCH 18/34] =?UTF-8?q?docs:=20add=20TOC=20(=F0=9F=98=AD)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit thanks i hate it s/o https://github.com/jonschlinkert/markdown-toc --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 224bf7ccc..e9a3af0c5 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,23 @@ With `rdme`, you can manage your [OpenAPI](https://spec.openapis.org/oas/v3.1.0.html) (or [Swagger](https://swagger.io/specification/v2/)) definition and sync it to your API reference docs 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 ReadMe project and managing project versions. +## Table of Contents + +- [Configuration](#configuration) + - [Setup](#setup) + - [Authentication](#authentication) +- [Usage](#usage) + - [Common `rdme` Options](#common-rdme-options) + - [GitHub Actions](#github-actions) + - [OpenAPI / Swagger](#openapi--swagger) + - [Docs](#docs) + - [Changelogs](#changelogs) + - [Custom Pages](#custom-pages) + - [Versions](#versions) + - [Categories](#categories) + - [Open Your ReadMe Project in Your Browser](#open-your-readme-project-in-your-browser) +- [Future](#future) + ## Configuration ### Setup From 99d505b3c35837c4c339ce932e5902a706c74be8 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Tue, 18 Oct 2022 12:32:05 -0500 Subject: [PATCH 19/34] chore: removing emojis in headings --- documentation/github-actions-docs-example.md | 6 +++--- documentation/github-actions-openapi-example.md | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/github-actions-docs-example.md b/documentation/github-actions-docs-example.md index 65ec6ca27..af561c7d4 100644 --- a/documentation/github-actions-docs-example.md +++ b/documentation/github-actions-docs-example.md @@ -18,7 +18,7 @@ Check out `.github/workflows/docs.yml` for more info on this! Do you have Markdown files stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync them to ReadMe every time they're updated in GitHub. Let's go over how to set this up! -## "Automagical" Workflow File Generation πŸͺ„ +## "Automagical" Workflow File Generation To set up a GitHub Actions workflow for syncing a directory of Markdown docs, the fastest and easiest way to do so is by running the following command on your local machine: @@ -28,11 +28,11 @@ rdme docs [path-to-directory-of-markdown] --github This will scan the directory for Markdown files, sync them to ReadMe, and then create your GitHub Actions workflow file. Once that's done, create your [repository secret](url), push your workflow file to GitHub, and get syncing! 🎊 -## Constructing a GitHub Actions Workflow File By Hand πŸ”¨ +## Constructing a GitHub Actions Workflow File By Hand > 🚧 Wait β€” there’s an easier way to do this! > -> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation-πŸͺ„). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing. +> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing. In order to construct the file by hand, you'll first want to grab a project version to ensure that your docs sync to the right place in your developer hub. That version will be passed via the `--version` flag. See below for a full example: diff --git a/documentation/github-actions-openapi-example.md b/documentation/github-actions-openapi-example.md index f2f6a5d8a..d6c1d57cf 100644 --- a/documentation/github-actions-openapi-example.md +++ b/documentation/github-actions-openapi-example.md @@ -17,7 +17,7 @@ Check out `.github/workflows/docs.yml` for more info on this! Is your OpenAPI definition stored on GitHub? With [the `rdme` GitHub Action](https://docs.readme.com/docs/rdme), you can sync it to ReadMe every time it's updated in GitHub. Let's go over how to set this up! -## "Automagical" Workflow File Generation πŸͺ„ +## "Automagical" Workflow File Generation To set up a GitHub Actions workflow for syncing an OpenAPI or Swagger definition, the fastest and easiest way to do so is by running the following command on your local machine: @@ -27,11 +27,11 @@ rdme openapi --github This will locate your OpenAPI definition, sync it to ReadMe, and then create your GitHub Actions workflow file. Once that's done, create your [repository secret](url), push your workflow file to GitHub, and get syncing! 🎊 -## Constructing a GitHub Actions Workflow File By Hand πŸ”¨ +## Constructing a GitHub Actions Workflow File By Hand > 🚧 Wait β€” there’s an easier way to do this! > -> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation-πŸͺ„). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing. +> The information below is useful if you have experience using GitHub Actions, but for most folks, we recommend using the steps [detailed above](#automagical-workflow-file-generation). The `rdme` CLI will ask you a few questions before automatically creating the GitHub Actions workflow file for you, complete with every parameter you need to get syncing. In order to construct the file by hand, 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. From 933a3a9e25b09935f68433ab2eb0498b668d4d61 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 19 Oct 2022 13:42:25 -0500 Subject: [PATCH 20/34] docs: better dependabot callouts per feedback from spang --- documentation/github-actions-docs-example.md | 4 ++++ documentation/github-actions-openapi-example.md | 4 ++++ documentation/rdme.md | 2 +- 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/documentation/github-actions-docs-example.md b/documentation/github-actions-docs-example.md index af561c7d4..5fc5b4fc4 100644 --- a/documentation/github-actions-docs-example.md +++ b/documentation/github-actions-docs-example.md @@ -62,3 +62,7 @@ jobs: ``` In the example above, every push to the `main` branch will sync the Markdown contents of the `documentation` directory to version 2.0 of your ReadMe project. + +> πŸ“˜ Keeping `rdme` up-to-date +> +> Note that `@RDME_VERSION` (used in the above example) 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). diff --git a/documentation/github-actions-openapi-example.md b/documentation/github-actions-openapi-example.md index d6c1d57cf..e0268c2cc 100644 --- a/documentation/github-actions-openapi-example.md +++ b/documentation/github-actions-openapi-example.md @@ -109,3 +109,7 @@ jobs: ``` In the example above, every push to the `main` branch will sync the OpenAPI file located at `./path-to-file.json` to the API specification `API_DEFINITION_ID` in your ReadMe project. + +> πŸ“˜ Keeping `rdme` up-to-date +> +> Note that `@RDME_VERSION` (used in the above example) 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). diff --git a/documentation/rdme.md b/documentation/rdme.md index 772a3f9d2..40a647f62 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -106,7 +106,7 @@ While there are [dozens of event options available](https://docs.github.com/acti > πŸ“˜ Keeping `rdme` up-to-date > -> 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). +> Note that `@RDME_VERSION` (used in the examples on this page) 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). ### GitHub Actions Quick Start From b46ff0c1fe9d6e5030952e1b224d074b3288eb05 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Wed, 19 Oct 2022 13:42:36 -0500 Subject: [PATCH 21/34] chore: move callout per feedback from spang --- documentation/rdme.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/documentation/rdme.md b/documentation/rdme.md index 40a647f62..52ba8a2c1 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -193,15 +193,6 @@ Want to start syncing? We have several example workflow files available: 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 rdme@RDME_VERSION` in a Node.js environment. See below for several examples. -> 🚧 Secretly store your ReadMe API Key! -> -> Nearly every CI service has a way to securely add secrets so that they're not exposed in your scripts and build logs. We strongly recommend using such a feature for storing your ReadMe API key. The following examples use `$README_API_KEY`, which is how you typically load such variables in your scripts. We've included some links below on how to configure these for the respective examples: -> -> - [Bitbucket Pipelines](https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Secured-variables) -> - [CircleCI](https://circleci.com/docs/env-vars/) -> - [GitLab CI](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project) -> - [Travis CI](https://docs.travis-ci.com/user/environment-variables) - + + + - [CLI Configuration](#cli-configuration) - [Setup](#setup) - [Authentication](#authentication) @@ -32,6 +45,8 @@ Not using ReadMe for your docs? No worries. `rdme` has a variety of tools to hel - [Open Your ReadMe Project in Your Browser](#open-your-readme-project-in-your-browser) - [Future](#future) + + ## CLI Configuration ### Setup From 16f7fd5098fea5a4e8b39be624dcc878a4a86114 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 27 Oct 2022 17:00:19 -0400 Subject: [PATCH 29/34] chore: "guides", docs example usage --- README.md | 2 +- documentation/rdme.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5febcbaf7..563f417c3 100644 --- a/README.md +++ b/README.md @@ -249,7 +249,7 @@ This command also has a dry run mode, which can be useful for initial setup and If you wish to delete documents from ReadMe that are no longer present in your local directory: ```sh -rdme docs:prune path-to-directory-of-markdown +rdme docs:prune [path-to-directory-of-markdown] ``` ### Changelogs πŸ“£ diff --git a/documentation/rdme.md b/documentation/rdme.md index 5b7dc362c..4abaa5b2c 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -29,7 +29,7 @@ Check out `.github/workflows/docs.yml` for more info on this! Build status

-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! +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 Guides or API reference on ReadMe every time you've ship new code. Enter `rdme`: ReadMe's official command-line interface (CLI) and GitHub Action! With `rdme`, you can create workflows for a variety of use cases, including: @@ -51,7 +51,7 @@ To see detailed CLI setup instructions and all available commands, check out [th > - There are slight variations in the YAML front matter attributes for each respective section of your documentation. For example, Changelog has a `type` attribute which you can set to `added`. See [Specifying Other Attributes](#specifying-other-attributes) for more information. > - In addition to Markdown, Custom Pages also supports HTML files. If you pass an HTML file into the `custompages` commands, the page will have the `htmlmode` flag set to `true` and it will conversely be set to `false` for Markdown files. You can override this in the YAML front matter. -In order to sync a directory of Markdown files to your guides, your Changelog, or your Custom Pages, 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!): +In order to sync Markdown files to your Guides, your Changelog, or your Custom Pages, 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 --- @@ -91,9 +91,9 @@ You can also specify several other page attributes in your YAML front matter, su If you're setting up new pages or if you're generally unsure if you've set up your page attributes correctly, each command has a dry run mode. This will allow you preview the changes without actually creating/updating any docs in ReadMe, which can be extremely useful for initial setup (oh, and we have [comprehensive debugging options](#troubleshooting) available as well!). To enable dry run mode, use the `--dryRun` flag: ```sh -rdme docs [path-to-directory-of-markdown] --version={project-version} --dryRun -rdme changelogs [path-to-directory-of-markdown] --dryRun -rdme custompages [path-to-directory-of-markdown] --dryRun +rdme docs [path] --version={project-version} --dryRun +rdme changelogs [path] --dryRun +rdme custompages [path] --dryRun ``` The command output will indicate whether each page is being created or updated alongside all processed page attributes. From 49de3952135a81ad439c9d47a12908b0affcab86 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 27 Oct 2022 17:05:44 -0400 Subject: [PATCH 30/34] chore: swap emoji --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 563f417c3..227a3ed61 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ https://github.com/jonschlinkert/markdown-toc/issues/119 - [Usage](#usage) - [Common `rdme` Options](#common-rdme-options) - [OpenAPI / Swagger πŸ“š](#openapi--swagger-) - - [Docs πŸ“˜](#docs-) + - [Docs πŸ“–](#docs-) - [Changelogs πŸ“£](#changelogs-) - [Custom Pages πŸ“„](#custom-pages-) - [Versions ⏳](#versions-) @@ -232,7 +232,7 @@ rdme openapi:reduce [path-to-file.json] The command will ask you a couple questions about how you wish to reduce the file and then do so. And as with the `openapi` command, you can also [omit the file path](#omitting-the-file-path). -### Docs πŸ“˜ +### Docs πŸ“– 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 on setting up your front matter. From d884bae8e3231094689c538cbf29c196016ffd98 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Thu, 27 Oct 2022 19:09:25 -0400 Subject: [PATCH 31/34] chore: fix TOC --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3ccdc4c45..4263f2d24 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,8 @@ https://github.com/jonschlinkert/markdown-toc/issues/119 - [Usage](#usage) - [Common `rdme` Options](#common-rdme-options) - [OpenAPI / Swagger πŸ“š](#openapi--swagger-) - - [Docs πŸ“–](#docs-) - - [Changelogs πŸ“£](#changelogs-) + - [Docs (a.k.a. Guides) πŸ“–](#docs-aka-guides-) + - [Changelog πŸ“£](#changelog-) - [Custom Pages πŸ“„](#custom-pages-) - [Versions ⏳](#versions-) - [Categories πŸͺ£](#categories-) From ea6175536717bc8300b02fd5e26df9d1e8277c79 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 28 Oct 2022 12:08:33 -0400 Subject: [PATCH 32/34] chore: use our reducer people --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4263f2d24..c4a46c548 100644 --- a/README.md +++ b/README.md @@ -224,7 +224,7 @@ Similar to the `openapi` command, you can also [omit the file path](#omitting-th #### Reducing an API Definition -We also offer a tool that allows you to reduce a large API definition down to a specific set of tags or paths. This can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain. +We also offer a tool that allows you to reduce a large API definition down to a specific set of tags or paths (again, no ReadMe account required!). This can be useful if you're debugging a problematic schema somewhere, or if you have a file that is too big to maintain. ```sh rdme openapi:reduce [path-to-file.json] From 3ba7bcb5bd669c38cb2c9ac18b2317128d75afbf Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 28 Oct 2022 17:32:44 -0400 Subject: [PATCH 33/34] fix: add emoji instead of period --- README.md | 2 +- documentation/rdme.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c4a46c548..ec7aa94ec 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![rdme](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com)

- ReadMe's official command-line interface (CLI) and GitHub Action. + ReadMe's official command-line interface (CLI) and GitHub Action 🌊

diff --git a/documentation/rdme.md b/documentation/rdme.md index 4abaa5b2c..16d8e4d49 100644 --- a/documentation/rdme.md +++ b/documentation/rdme.md @@ -19,7 +19,7 @@ Check out `.github/workflows/docs.yml` for more info on this! [![rdme](https://user-images.githubusercontent.com/8854718/195465739-0f0f83d5-2e18-4e6c-96ae-944e3bb6880a.png)](https://readme.com)

- ReadMe's official command-line interface (CLI) and GitHub Action. + ReadMe's official command-line interface (CLI) and GitHub Action 🌊

From 36654f2d923f3b445a223df4a013b8edc75f9d07 Mon Sep 17 00:00:00 2001 From: Kanad Gupta Date: Fri, 28 Oct 2022 17:46:57 -0400 Subject: [PATCH 34/34] chore: update package description --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 7b5594a0b..dc60df122 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "rdme", "version": "8.0.0-beta.8", - "description": "ReadMe's official CLI and GitHub Action wrapper.", + "description": "ReadMe's official CLI and GitHub Action.", "license": "MIT", "author": "ReadMe (https://readme.com)", "engines": {