{"id":16295120,"url":"https://github.com/wadackel/gha-docgen","last_synced_at":"2025-03-15T11:31:58.320Z","repository":{"id":154038985,"uuid":"631506820","full_name":"wadackel/gha-docgen","owner":"wadackel","description":":memo: Generate documentation based on the Metadata of the GitHub Action.","archived":false,"fork":false,"pushed_at":"2024-10-25T04:35:18.000Z","size":229,"stargazers_count":3,"open_issues_count":39,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-26T02:06:56.863Z","etag":null,"topics":["actions","docgen","document","generator","github","github-action","github-actions","markdown"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/gha-docgen","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wadackel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-23T08:29:03.000Z","updated_at":"2024-02-01T11:17:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"f8d2e105-38e0-4ad0-92f4-7192cdd3c344","html_url":"https://github.com/wadackel/gha-docgen","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wadackel%2Fgha-docgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wadackel%2Fgha-docgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wadackel%2Fgha-docgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wadackel%2Fgha-docgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wadackel","download_url":"https://codeload.github.com/wadackel/gha-docgen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221572639,"owners_count":16845696,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","docgen","document","generator","github","github-action","github-actions","markdown"],"created_at":"2024-10-10T20:17:40.942Z","updated_at":"2024-10-26T19:37:11.161Z","avatar_url":"https://github.com/wadackel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gha-docgen\n\n[![Build][badge-build]][build]\n[![npm][badge-npm]][npm]\n[![MIT LICENSE][badge-license]][license]\n[![code style: prettier][badge-prettier]][prettier]\n[![semantic-release: angular][badge-semantic-release]][semantic-release]\n\n`gha-docgen` generates documentation based on the [metadata](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions) of a GitHub Action, such as `action.yml`. To limit partial output, you can freely customize the document style at any time. Maintain flexibility while providing documentation driven by Metadata, and always offer consistent documentation to users.\n\nYou can see an example of an Action actually in use at [wadackel/files-sync-action](https://github.com/wadackel/files-sync-action).\n\n## Features\n\n- Usage is simple, just execute `$ gha-docgen`\n- The output focuses on content only, providing high flexibility for documentation\n- Supports the output of `description`, as well as `inputs` and `outputs`\n- Output styles supported include sections and tables\n\n## Installation\n\n```bash\n$ npm install --save-dev gha-docgen\n```\n\n## Usage\n\nI will explain how to use `gha-docgen`.\n\nThe following file is assumed for the `action.yml`, which is the metadata of the Action.\n\n`action.yml`\n\n```yaml\nname: 'DEMO Action'\ndescription: 'Here is an example of Action Metadata description. This is a description used in gha-docgen Usage.'\nauthor: 'wadackel'\n\ninputs:\n  github_token:\n    description: 'The GitHub token.'\n    required: true\n  github_api_url:\n    description: 'API URL of the GitHub server.'\n    default: 'https://api.github.com'\n  advanced_id:\n    description: |\n      Description including newlines is also supported.\n      Line break codes in YAML correspond to Markdown formatting and are correctly reflected.\n\noutputs:\n  pull_request_urls:\n    description: 'URL array of PRs created.'\n\nruns:\n  using: 'node16'\n  main: 'dist/index.js'\n```\n\n`gha-docgen` uses `README.md` by default. To specify the Metadata output location, use the format `gha-(description|inputs|outputs)-(start|end)` in the comments. All Metadata outputs are optional, and you can manually write content that doesn't require output.\n\n`README.md`\n\n```markdown\n# DEMO Action\n\nbadge...\n\n\u003c!-- gha-description-start --\u003e\n\u003c!-- gha-description-end --\u003e\n\n## Inputs\n\nOverview of Inputs.\n\n\u003c!-- gha-inputs-start --\u003e\n\u003c!-- gha-inputs-end --\u003e\n\n## Outputs\n\nOverview of Outputs.\n\n\u003c!-- gha-outputs-start --\u003e\n\u003c!-- gha-outputs-end --\u003e\n\n## LICENSE\n\nlicense...\n```\n\nFinally, run `gha-docgen`. By default, no flags are required.\n\n```bash\n$ npx gha-docgen\n```\n\nThe generated documentation will look like the following:\n\n\u003c!-- prettier-ignore-start --\u003e\n```markdown\n# DEMO Action\n\nbadge...\n\n\u003c!-- gha-description-start --\u003e\nHere is an example of Action Metadata description. This is a description used in gha-docgen Usage.\n\u003c!-- gha-description-end --\u003e\n\n## Inputs\n\nOverview of Inputs.\n\n\u003c!-- gha-inputs-start --\u003e\n### `github_token`\n\n**Required:** `true`  \n**Default:** n/a\n\nThe GitHub token.\n\n### `github_api_url`\n\n**Required:** `false`  \n**Default:** `https://api.github.com`\n\nAPI URL of the GitHub server.\n\n### `advanced_id`\n\n**Required:** `false`  \n**Default:** n/a\n\nDescription including newlines is also supported.  \nLine break codes in YAML correspond to Markdown formatting and are correctly reflected.\n\u003c!-- gha-inputs-end --\u003e\n\n## Outputs\n\nOverview of Outputs.\n\n\u003c!-- gha-outputs-start --\u003e\n### `pull_request_urls`\n\nURL array of PRs created.\n\u003c!-- gha-outputs-end --\u003e\n\n## LICENSE\n\nlicense...\n```\n\u003c!-- prettier-ignore-end --\u003e\n\nIf you want to customize the output style, please see [Output Styles](#output-styles).  \nFor examples of workflows that integrate with CI and continuously verify that the documentation is up-to-date, please see [CI Configuration Recipes](#ci-configuration-recipes).\n\n### CLI\n\nThe usage of the CLI is as follows:\n\n```bash\n$ npx gha-docgen --help\n\nUSAGE\n  $ gha-docgen [...files]\n\nARGUMENTS\n  files         List of paths to markdown files. Default is \"README.md\".\n\nFLAGS\n  --action, -a  File path to the Metadata for the Action. Default is \"action.yml\" or \"action.yaml\".\n  --style, -s   Output style. Available styles are \"section:h1\" through \"section:h6\" at different heading levels, and \"table\". Default is \"section:h3\".\n  --debug, -d   Enables debug output. Default is disabled.\n\nEXAMPLES\n  $ gha-docgen\n  $ gha-docgen docs.md\n  $ gha-docgen --action \"./subdir/action.yml\"\n  $ gha-docgen --style \"section:h1\"\n  $ gha-docgen --style \"section:h2\"\n  $ gha-docgen --style \"section:h3\"\n  $ gha-docgen --style \"section:h4\"\n  $ gha-docgen --style \"section:h5\"\n  $ gha-docgen --style \"section:h6\"\n  $ gha-docgen --style \"table\"\n  $ gha-docgen --debug\n```\n\n## Output Styles\n\nThere are two main output styles supported.\n\n### `section:h{n}`\n\nOutputs in a section format consisting of headings and descriptions. `{n}` can be specified with a heading level of `1-6`.\n\nIf the description contains a newline character, the newline character is converted to `  \\n`, and the line is correctly broken on Markdown.\n\n**Output:**\n\n\u003c!-- prettier-ignore-start --\u003e\n```markdown\n### `github_token`\n\n**Required:** `true`  \n**Default:** n/a\n\nThe GitHub token.\n```\n\u003c!-- prettier-ignore-end --\u003e\n\n### `table`\n\nOutputs in a table format.\n\nIf the description contains a newline character, the newline character is converted to `\u003cbr /\u003e`, and the line is correctly broken within the table.  \nIf the content contains a `|`, it is escaped to `\\|`.\n\n**Output:**\n\n\u003c!-- prettier-ignore-start --\u003e\n```markdown\n| ID | Required | Default | Description |\n| :-- | :-- | :-- | :-- |\n| `github_token` | :white_check_mark: | n/a | The GitHub token. |\n```\n\u003c!-- prettier-ignore-end --\u003e\n\n## CI Configuration Recipes\n\nI will introduce a GitHub Actions Workflow to ensure that the documentation is always up-to-date.\n\nIn this example, the status will fail if the contents of `action.yml` are updated, but the remote repository is updated without running `gha-docgen`.\n\nFirst, register the `docgen` script in `package.json`. In this example, [prettier][prettier] is used, but the use of prettier is optional. However, using formatters like prettier is recommended.\n\n`package.json`\n\n```json\n{\n  \"scripts\": {\n    \"docgen\": \"gha-docgen \u0026\u0026 prettier --write README.md\"\n  }\n}\n```\n\nWrite a step that generates documentation and returns an exit code of `0` if a diff is detected on Git:\n\n`.github/workflows/\u003cyour_workflow_name\u003e.yml`\n\n```yaml\nname: 'ci'\non:\n  pull_request:\n    types:\n      - synchronize\n      - opened\n      - reopened\n  push:\n    branches:\n      - main\n      - 'releases/*'\njobs:\n  docgen:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n\n      - uses: actions/setup-node@v3\n        with:\n          node-version: 16\n\n      - name: Install dependencies\n        run: npm ci\n\n      - name: Generate documentation\n        run: npm run docgen\n\n      - name: Compare the expected and actual README.md\n        run: |\n          if [ \"$(git diff --ignore-space-at-eol README.md | wc -l)\" -gt \"0\" ]; then\n            echo \"Detected uncommitted changes after generate. See status below:\"\n            git diff\n            exit 1\n          fi\n```\n\nBy referring to these steps, you can verify that the documentation is up-to-date.\n\n## LICENSE\n\n[MIT © wadackel][license]\n\n[badge-build]: https://img.shields.io/github/actions/workflow/status/wadackel/gha-docgen/ci.yml?style=flat-square\n[badge-npm]: https://img.shields.io/npm/v/gha-docgen?style=flat-square\n[badge-license]: https://img.shields.io/github/license/wadackel/gha-docgen?style=flat-square\n[badge-prettier]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square\n[badge-semantic-release]: https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release\u0026style=flat-square\n[build]: https://github.com/wadackel/gha-docgen/actions/workflows/ci.yml\n[npm]: https://www.npmjs.com/package/gha-docgen\n[license]: ./LICENSE\n[prettier]: https://github.com/prettier/prettier\n[semantic-release]: https://github.com/semantic-release/semantic-release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwadackel%2Fgha-docgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwadackel%2Fgha-docgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwadackel%2Fgha-docgen/lists"}