{"id":26958591,"url":"https://github.com/tmknom/actdocs","last_synced_at":"2025-04-03T04:20:23.115Z","repository":{"id":39892967,"uuid":"474557214","full_name":"tmknom/actdocs","owner":"tmknom","description":"Generate documentation from Actions and Reusable Workflows.","archived":false,"fork":false,"pushed_at":"2025-02-02T10:05:35.000Z","size":159,"stargazers_count":11,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-02T11:18:54.270Z","etag":null,"topics":["docs-generator","github","github-actions"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tmknom.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-27T06:43:48.000Z","updated_at":"2025-02-02T10:05:37.000Z","dependencies_parsed_at":"2024-06-21T08:42:06.822Z","dependency_job_id":"be3a8a71-7abf-47ae-94fd-91c56937c5d9","html_url":"https://github.com/tmknom/actdocs","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":"tmknom/general-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknom%2Factdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknom%2Factdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknom%2Factdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tmknom%2Factdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tmknom","download_url":"https://codeload.github.com/tmknom/actdocs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246933995,"owners_count":20857167,"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":["docs-generator","github","github-actions"],"created_at":"2025-04-03T04:20:22.566Z","updated_at":"2025-04-03T04:20:23.092Z","avatar_url":"https://github.com/tmknom.png","language":"Go","readme":"# actdocs\n\nGenerate documentation from Actions and Reusable Workflows.\n\n## Description\n\nThe actdocs is a utility to generate documentation from GitHub Actions in Markdown format.\nIt's identified Actions or Reusable Workflows automatically, then formats appropriately.\n\n## Getting Started\n\nDocumentation is generated by the following command:\n\n```shell\ndocker run --rm -v \"$(pwd):/work\" -w \"/work\" \\\nghcr.io/tmknom/actdocs generate action.yml\n```\n\n### Actions\n\nFor example, write the following Actions and save it as `action.yml`.\n\n```yaml:action.yml\nname: Example Action\ndescription: A example for Actions.\ninputs:\n  hello:\n    default: \"Hello, world.\"\n    required: false\n    description: \"A input value.\"\n  answer:\n    default: 42\n    required: true\n    description: \"Answer to the Ultimate Question of Life, the Universe, and Everything.\"\noutputs:\n  result:\n    value: ${{ steps.main.outputs.result }}\n    description: \"A output value.\"\nruns:\n  using: composite\n  steps:\n    - id: main\n      shell: bash\n      run: echo \"result=example\" \u003e\u003e \"${GITHUB_OUTPUT}\"\n```\n\nRun `actdocs generate action.yml`, the following Markdown is output.\n\n\u003c!-- prettier-ignore-start --\u003e\n```markdown:README.md\n## Description\n\nA example for Actions.\n\n## Inputs\n\n| Name | Description | Default | Required |\n| :--- | :---------- | :------ | :------: |\n| hello | A input value. | `Hello, world.` | no |\n| answer | Answer to the Ultimate Question of Life, the Universe, and Everything. | `42` | yes |\n\n## Outputs\n\n| Name | Description |\n| :--- | :---------- |\n| result | A output value. |\n```\n\u003c!-- prettier-ignore-end --\u003e\n\nThese outputs can be sorted or injected into a specified file.\nFor more information, see [Usage](#usage).\n\n### Reusable Workflows\n\nSimply change the file you specify.\n\n```shell\ndocker run --rm -v \"$(pwd):/work\" -w \"/work\" \\\nghcr.io/tmknom/actdocs generate .github/workflows/lint.yml\n```\n\nThe actdocs automatically switches its behavior for Reusable Workflows.\n\n## Installation\n\n### Pull Docker image\n\nYou can pull from Docker Hub or GitHub Packages, whichever you prefer.\n\n**Docker Hub:**\n\n```shell\ndocker pull tmknom/actdocs\n```\n\n**GitHub Packages:**\n\n```shell\ndocker pull ghcr.io/tmknom/actdocs\n```\n\n### Download binary\n\nDownload the latest compiled binaries and put it anywhere in your executable path.\n\n- [GitHub Releases](https://github.com/tmknom/actdocs/releases/latest)\n\n### Build from source code\n\nIf you have Go 1.18+ development environment:\n\n```shell\ngit clone https://github.com/tmknom/actdocs\ncd actdocs/\nmake install\nactdocs --help\n```\n\n## Usage\n\n### Injection\n\nYou can inject to existing file.\nWrite the injection comments to Markdown.\n\n```markdown\n\u003c!-- actdocs start --\u003e\n\u003c!-- actdocs end --\u003e\n```\n\nUse `inject` command with `--file` or `-f` option.\n\n```shell\ndocker run --rm -v \"$(pwd):/work\" -w \"/work\" \\\nghcr.io/tmknom/actdocs inject --file README.md action.yml\n```\n\nThen, output is injected to the specified file.\n\n\u003e **Note**\n\u003e\n\u003e `inject` command can be used with `--dry-run` option to check the behavior without overwriting the file.\n\n### Sort\n\nYou can sort items by name and required.\nRun actdocs with `--sort` or `-s` option.\n\n```shell\ndocker run --rm -v \"$(pwd):/work\" -w \"/work\" \\\nghcr.io/tmknom/actdocs generate --sort action.yml\n```\n\nOf course, it can be used in combination with `inject` command.\n\nIf you prefer to sort in another way, try the following options:\n\n- `--sort-by-name`: sort by name only\n- `--sort-by-required`: sort by required only\n\n### Format\n\nYou can format to json.\nRun actdocs with `--format` option.\n\n```shell\ndocker run --rm -v \"$(pwd):/work\" -w \"/work\" \\\nghcr.io/tmknom/actdocs generate --format=json action.yml\n```\n\nSupported format is `markdown` and `json`.\n\n### Show help\n\nFor full details, run `docker run --rm ghcr.io/tmknom/actdocs --help`.\n\n```shell\nGenerate documentation from Actions and Reusable Workflows\n\nUsage:\n  actdocs [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  generate    Generate documentation\n  help        Help about any command\n  inject      Inject generated documentation to existing file\n\nFlags:\n      --debug              show debugging output\n      --format string      output format [markdown json] (default \"markdown\")\n  -h, --help               help for actdocs\n      --omit               omit for markdown if item not exists\n  -s, --sort               sort items by name and required\n      --sort-by-name       sort items by name\n      --sort-by-required   sort items by required\n  -v, --version            version for actdocs\n\nUse \"actdocs [command] --help\" for more information about a command.\n```\n\n## Maintainer Guide\n\n\u003c!-- markdownlint-disable no-inline-html --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eClick to see details\u003c/summary\u003e\n\n### Requirements\n\n- [GNU Make](https://www.gnu.org/software/make/)\n- [Docker](https://docs.docker.com/get-docker/)\n- [GitHub CLI](https://cli.github.com/)\n\n### Development\n\nYou can use the `make` command.\n\n**Build**:\n\n```shell\nmake build\n```\n\n**Test**:\n\n```shell\nmake test\n```\n\n**Lint**:\n\n```shell\nmake lint\n```\n\nFor more information, run `make help`.\n\n### CI\n\nWhen create a pull request, the following workflows are executed automatically at GitHub Actions.\n\n- [Test](/.github/workflows/test.yml)\n- [Lint Go](/.github/workflows/lint-go.yml)\n- [Lint Markdown](/.github/workflows/lint-markdown.yml)\n- [Lint YAML](/.github/workflows/lint-yaml.yml)\n- [Lint Action](/.github/workflows/lint-action.yml)\n- [Lint Shell](/.github/workflows/lint-shell.yml)\n\n### Release\n\n#### 1. Bump up to a new version\n\nRun the following command to bump up.\n\n```shell\nmake bump\n```\n\nThis command will execute the following steps:\n\n1. Update [VERSION](/VERSION)\n2. Commit, push, and create a pull request\n3. Open the web browser automatically for reviewing pull request\n\nThen review and merge, so the release is ready to go.\n\n#### 2. Publish the new version\n\nRun the following command to publish a new tag at GitHub.\n\n```shell\nmake release\n```\n\nThen [releasing workflow with GoReleaser](/.github/workflows/release.yml) is run automatically at GitHub Actions\nthat executes the following steps.\n\n1. Build executable binaries for Linux, Windows and Darwin\n2. Create a new GitHub Release, and publish binaries\n3. Push Docker images to Docker Hub and GitHub Packages\n\nFinally, we can use the new version! :tada:\n\n### Administration\n\n#### Package management\n\n- Binaries\n  - [GitHub Releases](https://github.com/tmknom/actdocs/releases/latest)\n- Docker images\n  - [Docker Hub](https://hub.docker.com/repository/docker/tmknom/actdocs)\n  - [GitHub Packages](https://github.com/tmknom/actdocs/pkgs/container/actdocs)\n\n#### Dependency management\n\nUse Dependabot version updates.\nFor more information, see [dependabot.yml](/.github/dependabot.yml).\n\n#### Secrets management\n\nStored environment secrets for the following environments in this repository.\n\n- **release**\n  - `DOCKERHUB_TOKEN`: Personal access token used to log against Docker Hub, and it's used by the [releasing workflow](/.github/workflows/release.yml).\n\n\u003c/details\u003e\n\u003c!-- markdownlint-enable no-inline-html --\u003e\n\n## Changelog\n\nSee [Releases](https://github.com/tmknom/actdocs/releases).\n\n## Source Repository\n\nSee [tmknom/actdocs](https://github.com/tmknom/actdocs/).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmknom%2Factdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftmknom%2Factdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftmknom%2Factdocs/lists"}