Automatically generate documentation for GitLab CI/CD components and CI/CD pipelines.
labdoc currently focuses on generating documentation for GitLab CI/CD components.
For an example, check out the labdoc component documentation, which is generated with labdoc.
In the future, the focus might shift to generating documentation for GitLab CI/CD Pipelines in general.
brew install erNail/tap/labdocCheck the releases for the available binaries.
Download the correct binary and add it to your $PATH.
go install github.com/erNail/labdocdocker pull ernail/labdoc:<LATEST_GITHUB_RELEASE_VERSION>Check out this repository and run the following:
go buildAdd the resulting binary to your $PATH.
labdoc currently expects all your CI/CD components to be in a directory, with all files on the root level.
By default, labdoc will use the templates directory.
The documentation is generated from the spec.inputs.*.description keywords,
and from the comments above the spec and the job keywords. Below is a minimal example:
---
# This comment will be used as description for the component
spec:
inputs:
my-input:
description: "This is used as description for the input"
my-other-input:
description: >-
This is a multiline input.
Since this output is used in a table, the `>-` is used to remove any newline characters
...
---
# This comment will be used as description for the job
my-job:
script: "echo Hello"
...labdoc generate --repoUrl github.com/erNail/labdocThis will generate a README.md in the templates directory.
The --repoUrl flag is required to generate the instructions on how to include your components.
labdoc generate --repoUrl github.com/erNail/labdoc --outputFile my/custom/path/README.mdlabdoc generate --repoUrl github.com/erNail/labdoc --componentDir my-componentslabdoc generate --repoUrl github.com/erNail/labdoc --checkThis command will not write the documentation to a file. It will only check if there is already a documentation, and if the content would change.
If the content remains unchanged, the command will exit with code 0. If there is no documentation, or the existing documentation would change, the command will exit with code 2.
labdoc generate --repoUrl github.com/erNail/labdoc --version 1.0.0By default, labdoc will generate instructions on how to include your component in other CI/CD pipelines.
If no version is specified, it will use latest as the version to use for the include.
By default, labdoc will generate documentation based on the
documentation template located in this repository.
You can create your own template and use it to generate documentation.
Simply create a file that uses Go Templating syntax and the type ComponentDocumentation,
then run the following:
labdoc generate --repoUrl github.com/erNail/labdoc --template templates/README.md.gotmplFor more details about the labdoc command, run the following:
labdoc -hYou can run labdoc via pre-commit.
Add the following to your .pre-commit-config.yml:
repos:
- repo: "https://github.com/erNail/labdoc"
rev: "<LATEST_GITHUB_RELEASE_VERSION>"
hooks:
- id: "labdoc-generate"
args:
- "--repoUrl=gitlab.com/erNail/labdoc"labdoc can be added to your GitLab CI/CD Pipeline as component.
Check the component documentation generated by labdoc for more details.
labdoccurrently only supports reading CI/CD component files from a directory with all files on the root level. These file names will be used as the component names.labdoccurrently expects all components to definespec:inputsand at least one job. Not defining one or the other can lead to unwanted behavior.- As a result of this,
labdocis currently not able to handle components that only include other components or GitLab CI/CD files.
Please check the open GitHub Issues to get an overview of the planned features.
To use all of the functionality listed below, you need to install all dependencies listed in the dev container setup script. If you are using this repositories dev container, you already have all dependencies installed.
task testtask linttask run -- --helptask run-generatetask buildtask build-imagetask test-github-actionstask release-test
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent