## Overview
The CI/CD solution by gitlba is great, however it has some limitations. The way how a pipeline is defined is definitelly one of thme. There's nothing woring about YAML itself, but gitlab pipeline is so complex to be written in a markup language.
For instance, let's assume there is the design where we want to trigger a pipeline from web UI or by API call. The pipeline consumes variables as input. There is no way how to define variable's type, options or if it's required or if it shouldn't be overriden. This sort of information is always part of a documentation. This package provides functionality to create simple documentation of *workflow* section, which can contain all of these infromation.
In my opinion, the *workflow* section should be part of every clean/nice pipeline definition ("code").
Let's define the naming convention, which covers some scenarios, and all other information write to comment. I know, comments sound awful, but it is the most safe way to achieve what we need.
## How does it work
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.
### Readme file
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.
### 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
```
## Usage
The tool can be used from command line or imported as module in a code. It requires only two parameters on input:
- path to yaml file containing thw *workflow* section
- path to documentation file where generated table is inserted to
### Command line
The packegs is called **glcidocs** and consumes following arguments:
- **--ci-file [**_optional_**]**
<br>Path to the file containing workflow section.
<br>Default value is *.gitlab-ci.yml*
- **--doc-file [**_optional_**]**
<br>Path to the output file.
<br>Default value is *README.md*
```bash
python -m glcidocs --ci-file my_workflow.yml --doc-file myREADME.md
```
### Import in code
The module *glcidocs* contains *create_docs* function. The functions consumes the same arguments as cli tool, but there are no default values set.
```python
import glcidocs
def run_create_docs():
docs = glcidocs.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": "glcidocs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "gitlab, pipeline, documentation, ci/cd, gitlab-ci",
"author": "Martin Mudroch",
"author_email": "martin.mudroch@proton.me",
"download_url": "https://files.pythonhosted.org/packages/00/18/20dc0f47b520e95cc61905fbb599a7e0bf9d5c6184812a05fdb64db91b1f/glcidocs-0.0.1b4.tar.gz",
"platform": null,
"description": "## Overview\r\n\r\nThe CI/CD solution by gitlba is great, however it has some limitations. The way how a pipeline is defined is definitelly one of thme. There's nothing woring about YAML itself, but gitlab pipeline is so complex to be written in a markup language.\r\n\r\nFor instance, let's assume there is the design where we want to trigger a pipeline from web UI or by API call. The pipeline consumes variables as input. There is no way how to define variable's type, options or if it's required or if it shouldn't be overriden. This sort of information is always part of a documentation. This package provides functionality to create simple documentation of *workflow* section, which can contain all of these infromation.\r\n\r\nIn my opinion, the *workflow* section should be part of every clean/nice pipeline definition (\"code\").\r\nLet's define the naming convention, which covers some scenarios, and all other information write to comment. I know, comments sound awful, but it is the most safe way to achieve what we need.\r\n\r\n## How does it work\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\r\n### Readme file\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\r\n<br>*\\<!--PIPELINE_DOCS-->*\r\nIf token is present, the table is insreted below it.\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## Usage\r\nThe tool can be used from command line or imported as module in a code. It requires only two parameters on input:\r\n- path to yaml file containing thw *workflow* section\r\n- path to documentation file where generated table is inserted to\r\n\r\n### Command line\r\nThe packegs is called **glcidocs** and consumes following arguments:\r\n- **--ci-file [**_optional_**]**\r\n<br>Path to the file containing workflow section.\r\n<br>Default value is *.gitlab-ci.yml*\r\n- **--doc-file [**_optional_**]**\r\n<br>Path to the output file.\r\n<br>Default value is *README.md*\r\n\r\n```bash\r\npython -m glcidocs --ci-file my_workflow.yml --doc-file myREADME.md\r\n```\r\n\r\n### Import in code\r\nThe module *glcidocs* 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 glcidocs\r\n\r\n\r\ndef run_create_docs():\r\n docs = glcidocs.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.0.1b4",
"project_urls": {
"Homepage": "https://github.com/martin356/gitlab-ci-docs"
},
"split_keywords": [
"gitlab",
" pipeline",
" documentation",
" ci/cd",
" gitlab-ci"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ce308216deaebea333e6ebf89db26e05cbd5f4ae05f11a831598433ac316eb5",
"md5": "12ef4f7dd7ce0885bc9a3fc7b932de5c",
"sha256": "552b5e1398f2b834a19f0d492792591bb82b8d80befeeca04ce36c3f47aa684c"
},
"downloads": -1,
"filename": "glcidocs-0.0.1b4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12ef4f7dd7ce0885bc9a3fc7b932de5c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7114,
"upload_time": "2024-04-02T21:37:52",
"upload_time_iso_8601": "2024-04-02T21:37:52.092909Z",
"url": "https://files.pythonhosted.org/packages/0c/e3/08216deaebea333e6ebf89db26e05cbd5f4ae05f11a831598433ac316eb5/glcidocs-0.0.1b4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "001820dc0f47b520e95cc61905fbb599a7e0bf9d5c6184812a05fdb64db91b1f",
"md5": "6910ce276bfb861f6c0f067851ecb48a",
"sha256": "27cfe39febd3bc3c0c9890a1f4b35504985eb18519b9d57f0d2898e66b1c6649"
},
"downloads": -1,
"filename": "glcidocs-0.0.1b4.tar.gz",
"has_sig": false,
"md5_digest": "6910ce276bfb861f6c0f067851ecb48a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6484,
"upload_time": "2024-04-02T21:37:55",
"upload_time_iso_8601": "2024-04-02T21:37:55.612337Z",
"url": "https://files.pythonhosted.org/packages/00/18/20dc0f47b520e95cc61905fbb599a7e0bf9d5c6184812a05fdb64db91b1f/glcidocs-0.0.1b4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-02 21:37:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "martin356",
"github_project": "gitlab-ci-docs",
"github_not_found": true,
"lcname": "glcidocs"
}
JSON
