gitlab-docs 1.0.5
A tool that automatically generates gitlab documentation from yaml files
Requires Python: <4.0.0,>=3.12.11

# Gitlab Docs

## 📖 Overview
GitLab Docs is your portable, Python-powered sidekick for keeping GitLab CI/CD pipelines well-documented.
If your system supports Python 3, you can install it instantly — no complex setup, no platform restrictions.

### 💡 Why it matters:

Code documentation is crucial.

Pipeline documentation is critical.

As pipelines grow, the what, when, and where of your workflows often get lost.

That’s where GitLab Docs comes in — a simple, elegant CLI tool that automatically generates and updates Markdown documentation for your pipelines, right alongside your code.

### ✨ Key Features
🛠 Portable — Works anywhere Python 3 runs.

📜 Markdown Output — Friendly for developers, perfect for GitLab README integration.

🔄 Auto-Update Mode — Insert or refresh documentation between customizable markers.

🧩 Multi-Block Support — Maintain different sections for different workflows.

🧪 Dry Run Mode — Preview changes without touching files.

### Python

```bash
pip3 install --user gitlab-docs
```

### Docker

```bash
docker run -v ${PWD}:/gitlab-docs charlieasmith93/gitlab-docs
```
or

```bash
podman run -it -v $(PWD):/gitlab-docs charlieasmith93/gitlab-docs
```

[comment]: <> (gitlab-docs-opening-auto-generated)

# GITLAB DOCS - .gitlab-ci.yml

## Inputs

|     Key     |           Value           | Description | Options  | Expand |
| :---------: | :-----------------------: | :---------: | :------: | :----: |
|  job-stage  |    {'default': 'test'}    |   &#x274c;  | &#x274c; |  true  |
| environment | {'default': 'production'} |   &#x274c;  | &#x274c; |  true  |


## Variables

|     Key     |     Value      | Description | Options  | Expand |
| :---------: | :------------: | :---------: | :------: | :----: |
| APPLICATION |  gitlab-docs   |   &#x274c;  | &#x274c; |  true  |
| OUTPUT_FILE | GITLAB-DOCS.md |   &#x274c;  | &#x274c; |  true  |

## Jobs
<h4><span class="badge text-bg-secondary">.TEST:RULES</span></h4>

<hr>

| **Attribute** |                       **Value**                       |
| :-----------: | :---------------------------------------------------: |
|   **rules**   | ['if': '$CI_PIPELINE_SOURCE == "merge_request_event"' |
|               |    'if': '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH']   |
|   **stage**   |                          test                         |

<h4><span class="badge text-bg-info">MEGALINTER</span></h4>

<hr>

|   **Attribute**   |           **Value**            |
| :---------------: | :----------------------------: |
| **allow_failure** |              True              |
|    **extends**    |        ['.test:rules']         |
|     **image**     | oxsecurity/megalinter-ci_light |

| <span class="badge text-bg-danger">Attribute</span> | <span class="badge text-bg-warning">Key</span> | <span class="badge text-bg-success">Value</span> |
| :-------------------------------------------------: | :--------------------------------------------: | :----------------------------------------------: |
|                      variables                      |               DEFAULT_WORKSPACE                |                 $CI_PROJECT_DIR                  |


<h4><span class="badge text-bg-info">BEHAVE-TESTS</span></h4>

<hr>

| **Attribute** |      **Value**      |
| :-----------: | :-----------------: |
|  **extends**  |    ['.test:rules'   |
|               |  '.poetry:install'] |

| <span class="badge text-bg-danger">Attribute</span> | <span class="badge text-bg-warning">Key</span> | <span class="badge text-bg-success">Value</span> |
| :-------------------------------------------------: | :--------------------------------------------: | :----------------------------------------------: |
|                      variables                      |           POETRY_VIRTUALENVS_CREATE            |                      false                       |


<h4><span class="badge text-bg-info">BUMP-VERSION</span></h4>

<hr>

| **Attribute** |               **Value**               |
| :-----------: | :-----------------------------------: |
|   **image**   |             python:3.12.11            |
|   **rules**   | ['if': '$CI_COMMIT_BRANCH == "main"'] |
|   **stage**   |                 .post                 |

<h4><span class="badge text-bg-secondary">.BUILD:PYTHON</span></h4>

<hr>

|  **Attribute**  |      **Value**      |
| :-------------: | :-----------------: |
| **environment** |       release       |
|   **extends**   | ['.poetry:install'] |
|    **stage**    |        build        |

<h4><span class="badge text-bg-info">TEST-BUILD</span></h4>

<hr>

| **Attribute** |     **Value**     |
| :-----------: | :---------------: |
|  **extends**  | ['.build:python'] |

<h4><span class="badge text-bg-info">PUBLISH</span></h4>

<hr>

| **Attribute** |                    **Value**                    |
| :-----------: | :---------------------------------------------: |
|  **extends**  |               ['.poetry:install']               |
| **id_tokens** |      'PYPI_JWT': 'aud': 'https://pypi.org'      |
|   **rules**   | ['if': '$CI_COMMIT_REF_NAME == $CI_COMMIT_TAG'] |
|   **stage**   |                     publish                     |

<h4><span class="badge text-bg-info">DOCKER-BUILD</span></h4>

<hr>

| **Attribute** |                    **Value**                    |
| :-----------: | :---------------------------------------------: |
|   **image**   |                  docker:latest                  |
|   **rules**   | ['if': '$CI_COMMIT_REF_NAME != $CI_COMMIT_TAG'] |
|  **services** |                 ['docker:dind']                 |
|   **stage**   |                      build                      |
|    **tags**   |              ['gitlab-org-docker']              |

[comment]: <> (gitlab-docs-closing-auto-generated)

# Command Reference
## gitlab-docs

A command line tool to convert your gitlab-ci yml into markdown documentation.

### Usage

```
Usage: gitlab-docs [OPTIONS] COMMAND [ARGS]...
```

### Options
* `help`: 
  * Type: BOOL 
  * Default: `false`
  * Usage: `--help`

  Show this message and exit.



### CLI Help

```
Usage: gitlab-docs [OPTIONS] COMMAND [ARGS]...

  A command line tool to convert your gitlab-ci yml into markdown
  documentation.

Options:
  --help  Show this message and exit.

Commands:
  generate        Will scan through your gitlab-ci yml and build a markdown...
  get-attributes  Compared to the generate command, the get-attribute...
```


##  get-attributes

Compared to the generate command, the get-attribute command allows you to pass the properties you wish to document and produces a markdown table.
Args:
    OUTPUT_FILE (_type_): _description_
    DRY_MODE (_type_): _description_
    GLDOCS_CONFIG_FILE (_type_): _description_
    attributes (_type_): _description_
    json (_type_): _description_

### Usage

```
Usage: gitlab-docs get-attributes [OPTIONS]
```

### Options
* `attributes`: 
  * Type: STRING 
  * Default: `readme.md`
  * Usage: `--attributes
-a`

  Pass a comma seperated list of gitlab ci yml attributes


* `OUTPUT_FILE`: 
  * Type: STRING 
  * Default: `readme.md`
  * Usage: `--output-file
-o`

  Output location of the markdown documentation.


* `GLDOCS_CONFIG_FILE`: 
  * Type: STRING 
  * Default: `.gitlab-ci.yml`
  * Usage: `--input-config
-i`

  The Gitlab CI Input configuration file to generated documentation from.


* `json`: 
  * Type: BOOL 
  * Default: `false`
  * Usage: `--json
-j`

  Return results in json format.


* `help`: 
  * Type: BOOL 
  * Default: `false`
  * Usage: `--help`

  Show this message and exit.



### CLI Help

```
Usage: gitlab-docs get-attributes [OPTIONS]

  Compared to the generate command, the get-attribute command allows you to
  pass the properties you wish to document and produces a markdown table.
  Args:     OUTPUT_FILE (_type_): _description_     DRY_MODE (_type_):
  _description_     GLDOCS_CONFIG_FILE (_type_): _description_
  attributes (_type_): _description_     json (_type_): _description_

Options:
  -a, --attributes TEXT    Pass a comma seperated list of gitlab ci yml
                           attributes

  -o, --output-file TEXT   Output location of the markdown documentation.
  -i, --input-config TEXT  The Gitlab CI Input configuration file to generated
                           documentation from.

  -j, --json BOOLEAN       Return results in json format.
  --help                   Show this message and exit.
```


##  dumps

# Click-md
Create md files per each command, in format of `parent-command`, under the `--docsPath` directory.

### Usage

```
Usage: gitlab-docs dumps [OPTIONS]
```

### Options
* `basemodule` (REQUIRED): 
  * Type: STRING 
  * Default: `src.gitlab_docs`
  * Usage: `--baseModule`

  The base command module path to import


* `basecommand` (REQUIRED): 
  * Type: STRING 
  * Default: `gitlab_docs`
  * Usage: `--baseCommand`

  The base command function to import


* `docspath` (REQUIRED): 
  * Type: STRING 
  * Default: `docs/`
  * Usage: `--docsPath`

  The docs dir path to write the md files


* `help`: 
  * Type: BOOL 
  * Default: `false`
  * Usage: `--help`

  Show this message and exit.



### CLI Help

```
Usage: gitlab-docs dumps [OPTIONS]

  # Click-md Create md files per each command, in format of `parent-
  command`, under the `--docsPath` directory.

Options:
  --baseModule TEXT   The base command module path to import  [required]
  --baseCommand TEXT  The base command function to import  [required]
  --docsPath TEXT     The docs dir path to write the md files  [required]
  --help              Show this message and exit.
```


##  generate

Will scan through your gitlab-ci yml and build a markdown document from  the yml.

### Usage

```
Usage: gitlab-docs generate [OPTIONS]
```

### Options
* `detailed`: 
  * Type: BOOL 
  * Default: `false`
  * Usage: `--detailed`

  Will include workflow and rules from jobs.


* `DRY_MODE`: 
  * Type: BOOL 
  * Default: `false`
  * Usage: `--dry-mode
-d`

  If set will disable documentation from being written


* `OUTPUT_FILE`: 
  * Type: STRING 
  * Default: `readme.md`
  * Usage: `--output-file
-o`

  Output location of the markdown documentation.


* `GLDOCS_CONFIG_FILE`: 
  * Type: STRING 
  * Default: `.gitlab-ci.yml`
  * Usage: `--input-config
-i`

  The Gitlab CI Input configuration file to generated documentation from.


* `help`: 
  * Type: BOOL 
  * Default: `false`
  * Usage: `--help`

  Show this message and exit.



### CLI Help

```
Usage: gitlab-docs generate [OPTIONS]

  Will scan through your gitlab-ci yml and build a markdown document from
  the yml.

Options:
  --detailed               Will include workflow and rules from jobs.
  -d, --dry-mode           If set will disable documentation from being
                           written

  -o, --output-file TEXT   Output location of the markdown documentation.
  -i, --input-config TEXT  The Gitlab CI Input configuration file to generated
                           documentation from.

  --help                   Show this message and exit.
```



[comment]: <> (gitlab-docs-opening-auto-generated)

# GITLAB DOCS - .gitlab-ci.yml

## Inputs

+-------------+---------------------------+-------------+----------+--------+
|     Key     |           Value           | Description | Options  | Expand |
+-------------+---------------------------+-------------+----------+--------+
| environment | {'default': 'production'} |   &#x274c;  | &#x274c; |  true  |
|  job-stage  |    {'default': 'test'}    |   &#x274c;  | &#x274c; |  true  |
+-------------+---------------------------+-------------+----------+--------+


## Variables

+-------------+----------------+-------------+----------+--------+
|     Key     |     Value      | Description | Options  | Expand |
+-------------+----------------+-------------+----------+--------+
| APPLICATION |  gitlab-docs   |   &#x274c;  | &#x274c; |  true  |
| OUTPUT_FILE | GITLAB-DOCS.md |   &#x274c;  | &#x274c; |  true  |
+-------------+----------------+-------------+----------+--------+

## Jobs
<h4><span class="badge text-bg-secondary">.TEST:RULES</span></h4>

<hr>

+---------------+-------------------------------------------------------+
| **Attribute** |                       **Value**                       |
+---------------+-------------------------------------------------------+
|   **rules**   | ['if': '$CI_PIPELINE_SOURCE == "merge_request_event"' |
|               |    'if': '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH']   |
|   **stage**   |                          test                         |
+---------------+-------------------------------------------------------+

<h4><span class="badge text-bg-info">MEGALINTER</span></h4>

<hr>

+-------------------+--------------------------------+
|   **Attribute**   |           **Value**            |
+-------------------+--------------------------------+
| **allow_failure** |              True              |
|    **extends**    |        ['.test:rules']         |
|     **image**     | oxsecurity/megalinter-ci_light |
+-------------------+--------------------------------+

+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+
| <span class="badge text-bg-danger">Attribute</span> | <span class="badge text-bg-warning">Key</span> | <span class="badge text-bg-success">Value</span> |
+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+
|                      variables                      |               DEFAULT_WORKSPACE                |                 $CI_PROJECT_DIR                  |
+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+


<h4><span class="badge text-bg-info">BEHAVE-TESTS</span></h4>

<hr>

+---------------+---------------------+
| **Attribute** |      **Value**      |
+---------------+---------------------+
|  **extends**  |    ['.test:rules'   |
|               |  '.poetry:install'] |
+---------------+---------------------+

+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+
| <span class="badge text-bg-danger">Attribute</span> | <span class="badge text-bg-warning">Key</span> | <span class="badge text-bg-success">Value</span> |
+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+
|                      variables                      |           POETRY_VIRTUALENVS_CREATE            |                      false                       |
+-----------------------------------------------------+------------------------------------------------+--------------------------------------------------+


<h4><span class="badge text-bg-info">BUMP-VERSION</span></h4>

<hr>

+---------------+---------------------------------------+
| **Attribute** |               **Value**               |
+---------------+---------------------------------------+
|   **image**   |             python:3.12.11            |
|   **rules**   | ['if': '$CI_COMMIT_BRANCH == "main"'] |
|   **stage**   |                 .post                 |
+---------------+---------------------------------------+

<h4><span class="badge text-bg-secondary">.BUILD:PYTHON</span></h4>

<hr>

+-----------------+---------------------+
|  **Attribute**  |      **Value**      |
+-----------------+---------------------+
| **environment** |       release       |
|   **extends**   | ['.poetry:install'] |
|    **stage**    |        build        |
+-----------------+---------------------+

<h4><span class="badge text-bg-info">TEST-BUILD</span></h4>

<hr>

+---------------+-------------------+
| **Attribute** |     **Value**     |
+---------------+-------------------+
|  **extends**  | ['.build:python'] |
+---------------+-------------------+

<h4><span class="badge text-bg-info">PUBLISH</span></h4>

<hr>

+---------------+-------------------------------------------------+
| **Attribute** |                    **Value**                    |
+---------------+-------------------------------------------------+
|  **extends**  |               ['.poetry:install']               |
| **id_tokens** |      'PYPI_JWT': 'aud': 'https://pypi.org'      |
|   **rules**   | ['if': '$CI_COMMIT_REF_NAME == $CI_COMMIT_TAG'] |
|   **stage**   |                     publish                     |
+---------------+-------------------------------------------------+

<h4><span class="badge text-bg-info">DOCKER-BUILD</span></h4>

<hr>

+---------------+-------------------------------------------------+
| **Attribute** |                    **Value**                    |
+---------------+-------------------------------------------------+
|   **image**   |                  docker:latest                  |
|   **rules**   | ['if': '$CI_COMMIT_REF_NAME != $CI_COMMIT_TAG'] |
|  **services** |                 ['docker:dind']                 |
|   **stage**   |                      build                      |
|    **tags**   |              ['gitlab-org-docker']              |
+---------------+-------------------------------------------------+

[comment]: <> (gitlab-docs-closing-auto-generated)