## Motivation
Let's assume the design when we want to trigger a pipeline from web UI or by an API call. The pipeline consumes variables as input. It would be very helpful to know the type of a variable or its valid options. This kind of information is usually part of the documentation. This package provides functionality to automate the creation of this documentation.
<img alt="Generated table example" src="doc/table_sample.PNG">
## Overview
The output of this script is simple description (documentation) of *workflow* section. It parses workflow section and inserts it to readme file. Currently, output documentation is only as html table.
<br>Properties of variables are defined in comment using the format described in following section.
### Variable definition
As mentioned before, we write all parameters of a variable to a comment. Format of a comment is very simple.
1. **first part** describes if variable is required on input. By default a variable is considered as optional. To "set" is as required, put *required* to the comment - *# required*
1. **second part** descibes variable's type or valid options.
- **type** - starts with colon. Typename can be whatever made up. *:type*
- **choices** - dev|test
These parts are separated by space. Type and choices must not by combined.
#### Example
```yaml
ENV: dev # required dev|test|prod
ACCOUNT_ALIAS: null # required :str
IMAGE_TAG: 0.1.0 # :version
```
### Pipeline name
Using of the pipeline name improves readability of pipeline runs and also describes the task executed by the pipeline.
Variable **PIPELINE_NAME** is showed in the separated column of the table.
## Usage
The tool can be used from command line or imported as module in a code. Output is written to the readme file.
### Insert to the Readme
By default, the script inserts generated table in the beggining of the file. However, it is possible to mark position in the file where the table will be inserted. The mark token is <br>*\<!--PIPELINE_DOCS-->*
If token is present, the table is insreted below it.
### Command line
The package **gitlabcidocs** consumes following arguments:
<ul>
<li><b>--ci-file</b> <i>[optional]</i></li>
<ul style="list-style-type:none;">
<li>Path to the file containing workflow section.</li>
<li>Default value is <i>.gitlab-ci.yml</i></li>
</ul>
</ul>
<ul>
<li><b>--doc-file</b> <i>[optional]</i></li>
<ul style="list-style-type:none;">
<li>Path to the output file.</li>
<li>Default value is <i>README.md</i></li>
</ul>
</ul>
<ul>
<li><b>--include-all-rules, -a</b> <i>[optional]</i></li>
<ul style="list-style-type:none;">
<li>If set to *true*, all rules in the workflow section are included. Otherwise only rules which includes $CI_PIPELINE_SOURCE==web|api|pipeline in the if statement are documented.</li>
<li>Default is <i>true</i></li>
</ul>
</ul>
<ul>
<li><b>--include-global-vars, -g</b> <i>[optional]</i></li>
<ul style="list-style-type:none;">
<li>If set, global variables section is included.</li>
<li>Default value is <i>false</i></li>
</ul>
</ul>
```bash
python -m gitlabcidocs --ci-file my_workflow.yml --doc-file myREADME.md
```
### Import in code
The module *gitlab-ci-docs* contains *create_docs* function. The functions consumes the same arguments as cli tool, but there are no default values set.
```python
import gitlabcidocs
def run_create_docs():
docs = gitlabcidocs.create_docs(
ci_file_path='my_workflow.yml',
docs_file_path='README.md'
)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/martin356/gitlab-ci-docs",
"name": "gitlab-ci-docs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gitlab, pipeline, documentation, ci/cd, gitlab-ci, ci, workflow",
"author": "Martin Mudroch",
"author_email": "martin.mudroch@proton.me",
"download_url": "https://files.pythonhosted.org/packages/cb/4e/fa6ee71b818ae3fa857a8e088caed19acd175655afebfa58f7897805e612/gitlab_ci_docs-0.1.0b3.tar.gz",
"platform": null,
"description": "## Motivation\r\nLet's assume the design when we want to trigger a pipeline from web UI or by an API call. The pipeline consumes variables as input. It would be very helpful to know the type of a variable or its valid options. This kind of information is usually part of the documentation. This package provides functionality to automate the creation of this documentation.\r\n\r\n<img alt=\"Generated table example\" src=\"doc/table_sample.PNG\">\r\n\r\n## Overview\r\nThe output of this script is simple description (documentation) of *workflow* section. It parses workflow section and inserts it to readme file. Currently, output documentation is only as html table.\r\n<br>Properties of variables are defined in comment using the format described in following section.\r\n\r\n### Variable definition\r\nAs mentioned before, we write all parameters of a variable to a comment. Format of a comment is very simple.\r\n1. **first part** describes if variable is required on input. By default a variable is considered as optional. To \"set\" is as required, put *required* to the comment - *# required*\r\n1. **second part** descibes variable's type or valid options.\r\n - **type** - starts with colon. Typename can be whatever made up. *:type*\r\n - **choices** - dev|test\r\n\r\nThese parts are separated by space. Type and choices must not by combined.\r\n\r\n#### Example\r\n```yaml\r\nENV: dev # required dev|test|prod\r\nACCOUNT_ALIAS: null # required :str\r\nIMAGE_TAG: 0.1.0 # :version\r\n```\r\n\r\n### Pipeline name\r\nUsing of the pipeline name improves readability of pipeline runs and also describes the task executed by the pipeline.\r\n\r\nVariable **PIPELINE_NAME** is showed in the separated column of the table.\r\n\r\n## Usage\r\nThe tool can be used from command line or imported as module in a code. Output is written to the readme file.\r\n\r\n### Insert to the Readme\r\nBy default, the script inserts generated table in the beggining of the file. However, it is possible to mark position in the file where the table will be inserted. The mark token is <br>*\\<!--PIPELINE_DOCS-->*\r\n\r\nIf token is present, the table is insreted below it.\r\n\r\n### Command line\r\nThe package **gitlabcidocs** consumes following arguments:\r\n<ul>\r\n <li><b>--ci-file</b> <i>[optional]</i></li>\r\n <ul style=\"list-style-type:none;\">\r\n <li>Path to the file containing workflow section.</li>\r\n <li>Default value is <i>.gitlab-ci.yml</i></li>\r\n </ul>\r\n</ul>\r\n<ul>\r\n <li><b>--doc-file</b> <i>[optional]</i></li>\r\n <ul style=\"list-style-type:none;\">\r\n <li>Path to the output file.</li>\r\n <li>Default value is <i>README.md</i></li>\r\n </ul>\r\n</ul>\r\n<ul>\r\n <li><b>--include-all-rules, -a</b> <i>[optional]</i></li>\r\n <ul style=\"list-style-type:none;\">\r\n <li>If set to *true*, all rules in the workflow section are included. Otherwise only rules which includes $CI_PIPELINE_SOURCE==web|api|pipeline in the if statement are documented.</li>\r\n <li>Default is <i>true</i></li>\r\n </ul>\r\n</ul>\r\n<ul>\r\n <li><b>--include-global-vars, -g</b> <i>[optional]</i></li>\r\n <ul style=\"list-style-type:none;\">\r\n <li>If set, global variables section is included.</li>\r\n <li>Default value is <i>false</i></li>\r\n </ul>\r\n</ul>\r\n\r\n```bash\r\npython -m gitlabcidocs --ci-file my_workflow.yml --doc-file myREADME.md\r\n```\r\n\r\n### Import in code\r\nThe module *gitlab-ci-docs* contains *create_docs* function. The functions consumes the same arguments as cli tool, but there are no default values set.\r\n```python\r\nimport gitlabcidocs\r\n\r\n\r\ndef run_create_docs():\r\n docs = gitlabcidocs.create_docs(\r\n ci_file_path='my_workflow.yml',\r\n docs_file_path='README.md'\r\n )\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple generator of gitlab ci file documentation",
"version": "0.1.0b3",
"project_urls": {
"Homepage": "https://github.com/martin356/gitlab-ci-docs"
},
"split_keywords": [
"gitlab",
" pipeline",
" documentation",
" ci/cd",
" gitlab-ci",
" ci",
" workflow"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "82ad449b51a36e32910c8b639c4b6a3f1baf8e204923df5c9fbd23b762aeacad",
"md5": "e1f2c4bf001f091d649db4f802112568",
"sha256": "15f7a4f9ace8d44c262a0de710301846ffd1ebdcd899e581cbcf653098f5b865"
},
"downloads": -1,
"filename": "gitlab_ci_docs-0.1.0b3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e1f2c4bf001f091d649db4f802112568",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9674,
"upload_time": "2024-06-02T19:19:57",
"upload_time_iso_8601": "2024-06-02T19:19:57.915908Z",
"url": "https://files.pythonhosted.org/packages/82/ad/449b51a36e32910c8b639c4b6a3f1baf8e204923df5c9fbd23b762aeacad/gitlab_ci_docs-0.1.0b3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb4efa6ee71b818ae3fa857a8e088caed19acd175655afebfa58f7897805e612",
"md5": "b5a6167dd157efbf5d2a8d07db1b719d",
"sha256": "16589a15a4d939675cfbce87b32231a451bc642c54dafcf4273158c005dd7c46"
},
"downloads": -1,
"filename": "gitlab_ci_docs-0.1.0b3.tar.gz",
"has_sig": false,
"md5_digest": "b5a6167dd157efbf5d2a8d07db1b719d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7351,
"upload_time": "2024-06-02T19:19:59",
"upload_time_iso_8601": "2024-06-02T19:19:59.079821Z",
"url": "https://files.pythonhosted.org/packages/cb/4e/fa6ee71b818ae3fa857a8e088caed19acd175655afebfa58f7897805e612/gitlab_ci_docs-0.1.0b3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-02 19:19:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "martin356",
"github_project": "gitlab-ci-docs",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gitlab-ci-docs"
}
JSON
