Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate documentation from actions.yml #1239

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+69 −63
Open

Generate documentation from actions.yml #1239

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
  • Loading branch information
@stschulte
stschulte committed Mar 7, 2025
commit c6d37f6ecccd7d5bb9215983f745333421050c13
90 changes: 28 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -16,68 +16,34 @@ This action provides the following functionality for GitHub Actions users:

See [action.yml](action.yml)

<!-- start usage -->
```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: ''

# 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: ''

# 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

# 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: ''
```
<!-- end usage -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
<!-- prettier-ignore-start -->
<!-- BEGIN_GITHUB_ACTION_DOCS -->
## Inputs

| Name | Description | Default | Required |
|------|-------------|---------|:--------:|
| <a name="input_always_auth"></a> [always-auth](#input\_always\_auth) | Set always-auth in npmrc. | `false` | no |
| <a name="input_architecture"></a> [architecture](#input\_architecture) | Target architecture for Node to use. Examples: x86, x64. Will use system architecture by default. | | no |
| <a name="input_cache"></a> [cache](#input\_cache) | Used to specify a package manager for caching in the default directory. Supported values: npm, yarn, pnpm. | | no |
| <a name="input_cache_dependency_path"></a> [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 |
| <a name="input_check_latest"></a> [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 |
| <a name="input_node_version"></a> [node-version](#input\_node\_version) | Version Spec of the version to use. Examples: 12.x, 10.15.1, >=10.15.0. | | no |
| <a name="input_node_version_file"></a> [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 |
| <a name="input_registry_url"></a> [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 |
| <a name="input_scope"></a> [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 |
| <a name="input_token"></a> [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 |

## Outputs

| Name | Description |
|------|-------------|
| <a name="output_cache_hit"></a> [cache-hit](#output\_cache\_hit) | A boolean value to indicate if a cache was hit. |
| <a name="output_node_version"></a> [node-version](#output\_node\_version) | The installed node version. |
<!-- END_GITHUB_ACTION_DOCS -->
<!-- prettier-ignore-end -->
<!-- markdownlint-restore -->

**Basic:**

38 changes: 38 additions & 0 deletions package-lock.json
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 3 additions & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -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",