From c6d37f6ecccd7d5bb9215983f745333421050c13 Mon Sep 17 00:00:00 2001 From: Stefan Schulte Date: Mon, 3 Mar 2025 22:32:11 +0100 Subject: [PATCH] Generate documentation from actions.yml Right now the documentation of valid inputs (and outputs) seems to be manually maintained inside the `README.md` with a reference to the `actions.yml` file. Since this can be rather tedious to maintain this commit now uses [github-actions-docs][1] to automatically generate documentation. [1]: https://www.npmjs.com/package/github-action-docs --- README.md | 84 ++++++++++++++--------------------------------- package-lock.json | 38 +++++++++++++++++++++ package.json | 4 ++- 3 files changed, 66 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 0c554898..eae735f2 100644 --- a/README.md +++ b/README.md @@ -16,68 +16,34 @@ This action provides the following functionality for GitHub Actions users: See [action.yml](action.yml) - -```yaml -- uses: actions/setup-node@v4 - with: - # Version Spec of the version to use in SemVer notation. - # It also admits such aliases as lts/*, latest, nightly and canary builds - # Examples: 12.x, 10.15.1, >=10.15.0, lts/Hydrogen, 16-nightly, latest, node - node-version: '' + + + + +## Inputs - # File containing the version Spec of the version to use. Examples: package.json, .nvmrc, .node-version, .tool-versions. - # If node-version and node-version-file are both provided the action will use version from node-version. - node-version-file: '' +| Name | Description | Default | Required | +|------|-------------|---------|:--------:| +| [always-auth](#input\_always\_auth) | Set always-auth in npmrc. | `false` | no | +| [architecture](#input\_architecture) | Target architecture for Node to use. Examples: x86, x64. Will use system architecture by default. | | no | +| [cache](#input\_cache) | Used to specify a package manager for caching in the default directory. Supported values: npm, yarn, pnpm. | | no | +| [cache-dependency-path](#input\_cache\_dependency\_path) | Used to specify the path to a dependency file: package-lock.json, yarn.lock, etc. Supports wildcards or a list of file names for caching multiple dependencies. | | no | +| [check-latest](#input\_check\_latest) | Set this option if you want the action to check for the latest available version that satisfies the version spec. | | no | +| [node-version](#input\_node\_version) | Version Spec of the version to use. Examples: 12.x, 10.15.1, >=10.15.0. | | no | +| [node-version-file](#input\_node\_version\_file) | File containing the version Spec of the version to use. Examples: package.json, .nvmrc, .node-version, .tool-versions. | | no | +| [registry-url](#input\_registry\_url) | Optional registry to set up for auth. Will set the registry in a project level .npmrc and .yarnrc file, and set up auth to read in from env.NODE_AUTH_TOKEN. | | no | +| [scope](#input\_scope) | Optional scope for authenticating against scoped registries. Will fall back to the repository owner when using the GitHub Packages registry (https://npm.pkg.github.com/). | | no | +| [token](#input\_token) | Used to pull node distributions from node-versions. Since there's a default, this is typically not supplied by the user. When running this action on github.com, the default value is sufficient. When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting. | `${{ github.server_url == 'https://github.com' && github.token || '' }}` | no | - # Set this option if you want the action to check for the latest available version - # that satisfies the version spec. - # It will only get affect for lts Nodejs versions (12.x, >=10.15.0, lts/Hydrogen). - # Default: false - check-latest: false +## Outputs - # Target architecture for Node to use. Examples: x86, x64. Will use system architecture by default. - # Default: ''. The action use system architecture by default - architecture: '' - - # Used to pull node distributions from https://github.com/actions/node-versions. - # Since there's a default, this is typically not supplied by the user. - # When running this action on github.com, the default value is sufficient. - # When running on GHES, you can pass a personal access token for github.com if you are experiencing rate limiting. - # - # We recommend using a service account with the least permissions necessary. Also - # when generating a new PAT, select the least scopes necessary. - # - # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets) - # - # Default: ${{ github.server_url == 'https://github.com' && github.token || '' }} - token: '' - - # Used to specify a package manager for caching in the default directory. Supported values: npm, yarn, pnpm. - # Package manager should be pre-installed - # Default: '' - cache: '' - - # Used to specify the path to a dependency file: package-lock.json, yarn.lock, etc. - # It will generate hash from the target file for primary key. It works only If cache is specified. - # Supports wildcards or a list of file names for caching multiple dependencies. - # Default: '' - cache-dependency-path: '' - - # Optional registry to set up for auth. Will set the registry in a project level .npmrc and .yarnrc file, - # and set up auth to read in from env.NODE_AUTH_TOKEN. - # Default: '' - registry-url: '' - - # Optional scope for authenticating against scoped registries. - # Will fall back to the repository owner when using the GitHub Packages registry (https://npm.pkg.github.com/). - # Default: '' - scope: '' - - # Set always-auth option in npmrc file. - # Default: '' - always-auth: '' -``` - +| Name | Description | +|------|-------------| +| [cache-hit](#output\_cache\_hit) | A boolean value to indicate if a cache was hit. | +| [node-version](#output\_node\_version) | The installed node version. | + + + **Basic:** diff --git a/package-lock.json b/package-lock.json index 07f38dbb..a42bb55f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -31,6 +31,7 @@ "eslint-config-prettier": "^8.6.0", "eslint-plugin-jest": "^27.9.0", "eslint-plugin-node": "^11.1.0", + "github-action-docs": "^1.1.0", "jest": "^29.7.0", "jest-circus": "^29.7.0", "jest-each": "^29.7.0", @@ -3427,6 +3428,43 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/github-action-docs": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/github-action-docs/-/github-action-docs-1.1.0.tgz", + "integrity": "sha512-oKnOL7LGygSTZ5tOuWV49HQU+Gu1BUxHEDXbbPD63czliFYi6XbHm6kf3nzgTUuOsGccOh2IqA3/1GA9wHmbIg==", + "dev": true, + "license": "MIT", + "dependencies": { + "commander": "^13.1.0", + "yaml": "^2.7.0" + }, + "bin": { + "github-action-docs": "dist/bin.js" + } + }, + "node_modules/github-action-docs/node_modules/commander": { + "version": "13.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-13.1.0.tgz", + "integrity": "sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/github-action-docs/node_modules/yaml": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.7.0.tgz", + "integrity": "sha512-+hSoy/QHluxmC9kCIJyL/uyFmLmc+e5CFR5Wa+bpIhIj85LVb9ZH2nVnqrHoSvKogwODv0ClqZkmiSSaIH5LTA==", + "dev": true, + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/glob": { "version": "7.2.3", "resolved": "https://registry.npmjs.org/glob/-/glob-7.2.3.tgz", diff --git a/package.json b/package.json index 3f88a2c2..695997c3 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "lint": "eslint --config ./.eslintrc.js \"**/*.ts\"", "lint:fix": "eslint --config ./.eslintrc.js \"**/*.ts\" --fix", "test": "jest --coverage", - "pre-checkin": "npm run format && npm run lint:fix && npm run build && npm test" + "pre-checkin": "npm run gen-docs && npm run format && npm run lint:fix && npm run build && npm test", + "gen-docs": "github-action-docs --sections inputs outputs --output-file README.md --mode inject action.yml" }, "repository": { "type": "git", @@ -47,6 +48,7 @@ "eslint-config-prettier": "^8.6.0", "eslint-plugin-jest": "^27.9.0", "eslint-plugin-node": "^11.1.0", + "github-action-docs": "^1.1.0", "jest": "^29.7.0", "jest-circus": "^29.7.0", "jest-each": "^29.7.0",