{"id":15055457,"url":"https://github.com/ernail/labdoc","last_synced_at":"2025-04-10T03:40:59.219Z","repository":{"id":243255313,"uuid":"804510457","full_name":"erNail/labdoc","owner":"erNail","description":"Automatically generate documentation for GitLab CI/CD components and CI/CD pipelines","archived":false,"fork":false,"pushed_at":"2025-03-26T01:08:40.000Z","size":155,"stargazers_count":6,"open_issues_count":14,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-02T23:33:08.961Z","etag":null,"topics":["documentation","gitlab","gitlab-ci","go","markdown"],"latest_commit_sha":null,"homepage":"","language":"Go","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/erNail.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2024-05-22T18:14:35.000Z","updated_at":"2025-02-16T11:34:15.000Z","dependencies_parsed_at":"2024-06-14T00:06:53.245Z","dependency_job_id":"eecb97b5-1284-4acf-9b9b-6ca8cfaa9864","html_url":"https://github.com/erNail/labdoc","commit_stats":null,"previous_names":["ernail/labdoc"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Flabdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Flabdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Flabdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erNail%2Flabdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erNail","download_url":"https://codeload.github.com/erNail/labdoc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154962,"owners_count":21056541,"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":["documentation","gitlab","gitlab-ci","go","markdown"],"created_at":"2024-09-24T21:42:18.882Z","updated_at":"2025-04-10T03:40:59.199Z","avatar_url":"https://github.com/erNail.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# labdoc\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./docs/img/icon.png\" width=\"250\" alt=\"labdoc icon\"\u003e\n    \u003cp\u003e\n        Automatically generate documentation for GitLab CI/CD components and CI/CD pipelines.\n    \u003c/p\u003e\n\u003c/div\u003e\n\n## What is `labdoc`?\n\n`labdoc` currently focuses on generating documentation for [GitLab CI/CD components](https://docs.gitlab.com/ee/ci/components/).\nFor an example, check out the [`labdoc` component documentation](./templates/README.md), which is generated with `labdoc`.\n\nIn the future, the focus might shift to generating documentation for GitLab CI/CD Pipelines in general.\n\n## Getting Started\n\n### Install `labdoc`\n\n#### Via Homebrew\n\n```shell\nbrew install erNail/tap/labdoc\n```\n\n#### Via Binary\n\nCheck the [releases](https://github.com/erNail/labdoc/releases) for the available binaries.\nDownload the correct binary and add it to your `$PATH`.\n\n#### Via Go\n\n```shell\ngo install github.com/erNail/labdoc\n```\n\n#### Via Container\n\n```shell\ndocker pull ernail/labdoc:\u003cLATEST_GITHUB_RELEASE_VERSION\u003e\n```\n\n#### From Source\n\nCheck out this repository and run the following:\n\n```shell\ngo build\n```\n\nAdd the resulting binary to your `$PATH`.\n\n### Run `labdoc`\n\n#### Prepare your GitLab CI/CD components\n\n`labdoc` currently expects all your CI/CD components to be in a directory, with all files on the root level.\nBy default, `labdoc` will use the [`templates` directory](https://docs.gitlab.com/ee/ci/components/#directory-structure).\n\nThe documentation is generated from the `spec.inputs.*.description` keywords,\nand from the comments above the `spec` and the job keywords. Below is a minimal example:\n\n```yaml\n---\n# This comment will be used as description for the component\nspec:\n  inputs:\n    my-input:\n      description: \"This is used as description for the input\"\n    my-other-input:\n      description: \u003e-\n        This is a multiline input.\n        Since this output is used in a table, the `\u003e-` is used to remove any newline characters\n...\n\n---\n# This comment will be used as description for the job\nmy-job:\n  script: \"echo Hello\"\n...\n```\n\n#### Generate Documentation\n\n```shell\nlabdoc generate --repoUrl github.com/erNail/labdoc\n```\n\nThis will generate a `README.md` in the `templates` directory.\n\nThe `--repoUrl` flag is required to generate the instructions on how to include your components.\n\n#### Change the documentation output directory\n\n```shell\nlabdoc generate --repoUrl github.com/erNail/labdoc --outputFile my/custom/path/README.md\n```\n\n#### Change the component directory\n\n```shell\nlabdoc generate --repoUrl github.com/erNail/labdoc --componentDir my-components\n```\n\n#### Check if the documentation is up-to-date\n\n```shell\nlabdoc generate --repoUrl github.com/erNail/labdoc --check\n```\n\nThis command will not write the documentation to a file.\nIt will only check if there is already a documentation, and if the content would change.\n\nIf the content remains unchanged, the command will exit with code 0.\nIf there is no documentation, or the existing documentation would change, the command will exit with code 2.\n\n#### Include the version in the usage instructions\n\n```shell\nlabdoc generate --repoUrl github.com/erNail/labdoc --version 1.0.0\n```\n\nBy default, `labdoc` will generate instructions on how to include your component in other CI/CD pipelines.\nIf no version is specified, it will use `latest` as the version to use for the include.\n\n#### Custom Documentation Template\n\nBy default, `labdoc` will generate documentation based on the\n[documentation template](./internal/gitlab/resources/default-template.md.gotmpl) located in this repository.\n\nYou can create your own template and use it to generate documentation.\nSimply create a file that uses [Go Templating](https://pkg.go.dev/text/template) syntax and the [type `ComponentDocumentation`](./internal/gitlab/component_documentation.go),\nthen run the following:\n\n```shell\nlabdoc generate --repoUrl github.com/erNail/labdoc --template templates/README.md.gotmpl\n```\n\n#### More Details\n\nFor more details about the `labdoc` command, run the following:\n\n```shell\nlabdoc -h\n```\n\n### `pre-commit` Hook\n\nYou can run `labdoc` via [`pre-commit`](https://pre-commit.com/).\nAdd the following to your `.pre-commit-config.yml`:\n\n```yaml\nrepos:\n  - repo: \"https://github.com/erNail/labdoc\"\n    rev: \"\u003cLATEST_GITHUB_RELEASE_VERSION\u003e\"\n    hooks:\n      - id: \"labdoc-generate\"\n        args:\n          - \"--repoUrl=gitlab.com/erNail/labdoc\"\n```\n\n## Limitations\n\n- `labdoc` currently only supports reading CI/CD component files from a directory with all files on the root level.\n  These file names will be used as the component names.\n- `labdoc` currently expects all components to define `spec:inputs` and at least one job.\n  Not defining one or the other can lead to unwanted behavior.\n- As a result of this, `labdoc` is currently not able to handle components that only include other components\n  or GitLab CI/CD files.\n\n## Planned Features\n\nPlease check the open [GitHub Issues](https://github.com/erNail/homebrew-tap/issues)\nto get an overview of the planned features.\n\n## Development\n\n### Dependencies\n\nTo use all of the functionality listed below,\nyou need to install all dependencies listed in the [dev container setup script](.devcontainer/postCreateCommand.sh).\nIf you are using this repositories dev container, you already have all dependencies installed.\n\n### Testing\n\n```shell\ntask test\n```\n\n### Linting\n\n```shell\ntask lint\n```\n\n### Running\n\n```shell\ntask run -- --help\n```\n\n```shell\ntask run-generate\n```\n\n### Building\n\n```shell\ntask build\n```\n\n### Building Container Images\n\n```shell\ntask build-image\n```\n\n### Test GitHub Actions\n\n```shell\ntask test-github-actions\n```\n\n### Test Release\n\n```shell\ntask release-test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernail%2Flabdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fernail%2Flabdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fernail%2Flabdoc/lists"}