feat: add to_code filter and enable codeblocks for tabulated vars (#784)

This commit is contained in:
Robert Kaussow 2024-10-08 08:26:25 +02:00 committed by GitHub
parent 56864c153f
commit 4bb11fd6cd
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 284 additions and 15 deletions

View File

@ -96,6 +96,7 @@ class Generator:
autoescape=jinja2.select_autoescape(),
)
jenv.filters["to_nice_yaml"] = self._to_nice_yaml
jenv.filters["to_code"] = self._to_code
jenv.filters["deep_get"] = self._deep_get
jenv.filters["safe_join"] = self._safe_join
# keep the old name of the function to not break custom templates.
@ -127,6 +128,25 @@ class Generator:
yaml.dump(a, stream, **kw)
return stream.getvalue().rstrip()
def _to_code(self, a, to_multiline=False, skip_list_len=0, lang="plain"):
"""Wrap a string in backticks."""
if a is None or a == "":
return ""
if (isinstance(a, list) and len(a) < 1) or (isinstance(a, dict) and not a):
return ""
if isinstance(a, list) and len(a) == 1:
return f"`{a[0]}`"
if isinstance(a, list) and skip_list_len > 0 and len(a) > skip_list_len:
return a
if (isinstance(a, list)) and to_multiline:
return "```" + lang + "\n" + "\n".join(a) + "\n```"
return f"`{a}`"
def _deep_get(self, _, dictionary, keys):
default = None
return reduce(

View File

@ -17,13 +17,13 @@
{% endfor %}
|
{% for key, item in var | dictsort %}
|{{ key -}}
|{{ (item.value | default({}))[key] | default -}}
|{{ key | to_code -}}
|{{ (item.value | default({}))[key] | default | to_code -}}
{% if "description" in found_columns %}
|{{ item.description | default([]) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
{% endif %}
{% if "type" in found_columns %}
|{{ item.type | default([]) | join("<br />") -}}
|{{ item.type | default([]) | to_code(skip_list_len=1) | safe_join("<br />") -}}
{% endif %}
{% if "deprecated" in found_columns %}
|
@ -42,7 +42,7 @@ False
{% endif %}
{% endif %}
{% if "example" in found_columns %}
|{{ item.example | default([]) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
|{{ item.example | default([]) | to_code(skip_list_len=1) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
{% endif %}
|
{% endfor %}

View File

@ -17,13 +17,13 @@
{% endfor %}
|
{% for key, item in var | dictsort %}
|{{ key -}}
|{{ (item.value | default({}))[key] | default -}}
|{{ key | to_code -}}
|{{ (item.value | default({}))[key] | default | to_code -}}
{% if "description" in found_columns %}
|{{ item.description | default([]) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
{% endif %}
{% if "type" in found_columns %}
|{{ item.type | default([]) | join("<br />") -}}
|{{ item.type | default([]) | to_code(skip_list_len=1) | safe_join("<br />") -}}
{% endif %}
{% if "deprecated" in found_columns %}
|
@ -42,7 +42,7 @@ False
{% endif %}
{% endif %}
{% if "example" in found_columns %}
|{{ item.example | default([]) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
|{{ item.example | default([]) | to_code(skip_list_len=1) | safe_join("<br />") | replace("\n", "<br />") | replace("|", "\|") -}}
{% endif %}
|
{% endfor %}

View File

@ -9,7 +9,19 @@ Role to demonstrate ansible-doctor.
- [Requirements](#requirements)
- [Default Variables](#default-variables)
- [demo_role_unset](#demo_role_unset)
- [demo_bool](#demo_bool)
- [other_role_deprecated](#other_role_deprecated)
- [other_role_deprecated_info](#other_role_deprecated_info)
- [other_role_dict](#other_role_dict)
- [other_role_empty](#other_role_empty)
- [other_role_empty_dict](#other_role_empty_dict)
- [other_role_multiline_type](#other_role_multiline_type)
- [other_role_other_tags](#other_role_other_tags)
- [other_role_override](#other_role_override)
- [other_role_override_complex](#other_role_override_complex)
- [other_role_single](#other_role_single)
- [other_role_undefined_var](#other_role_undefined_var)
- [other_role_unset](#other_role_unset)
- [Discovered Tags](#discovered-tags)
- [Open Tasks](#open-tasks)
- [Dependencies](#dependencies)
@ -24,20 +36,183 @@ Role to demonstrate ansible-doctor.
## Default Variables
### demo_role_unset
### demo_bool
#### Default value
```YAML
demo_bool: true
```
#### Example usage
```YAML
demo_bool: false
```
### other_role_deprecated
**_Deprecated_**<br />
#### Default value
```YAML
other_role_deprecated: b
```
### other_role_deprecated_info
**_Deprecated:_** This variable is deprected since `v2.0.0` and will be removed in a future release.<br />
**_Type:_** string<br />
#### Default value
```YAML
other_role_deprecated_info: a
```
### other_role_dict
#### Default value
```YAML
other_role_dict:
key1:
sub: some value
```
#### Example usage
```YAML
other_role_dict:
key1:
sub: some value
# Inline description
key2:
sublist:
- subval1
- subval2
```
### other_role_empty
#### Default value
```YAML
other_role_empty: ''
```
### other_role_empty_dict
... or valid json can be used. In this case, the json will be automatically prefixed with the annotation key
and filters like `to_nice_yaml` can be used in templates. To get it working, the json need to be prefixed with a `$`.
#### Default value
```YAML
other_role_empty_dict: {}
```
#### Example usage
```YAML
other_role_empty_dict:
key1:
sub: some value
key2:
sublist:
- subval1
- subval2
```
### other_role_multiline_type
**_Type:_** string
list
dict<br />
#### Default value
```YAML
other_role_multiline_type: a
```
### other_role_other_tags
If a variable need some more explanation, this is a good place to do so.
#### Default value
```YAML
other_role_other_tags:
- package1
- package2
```
#### Example usage
```YAML
other_role_other_tags:
- package1
- package2
```
### other_role_override
#### Default value
```YAML
other_role_override: test
```
### other_role_override_complex
#### Default value
```YAML
other_role_override_complex:
foo: bar
second: value
```
### other_role_single
#### Default value
```YAML
other_role_single: b
```
### other_role_undefined_var
To highlight a variable that has not set a value by default, this is one way to achieve it.
Make sure to flag it as json value: `@var other_role_undefined_var: $ "_unset_"`
| Attribute | Description |
| --- | --- |
| value1 | desc1 |
#### Default value
```YAML
other_role_undefined_var: _unset_
```
### other_role_unset
Values can be plain strings, but there is no magic or autoformatting...
#### Default value
```YAML
demo_role_unset:
other_role_unset:
```
#### Example usage
```YAML
demo_role_unset: some_value
other_role_unset: some_value
```
## Discovered Tags

View File

@ -1,4 +1,78 @@
---
# @var demo_role_unset:description: Values can be plain strings, but there is no magic or autoformatting...
# @var demo_role_unset:example: demo_role_unset: some_value
demo_role_unset:
# @var other_role_unset:description: Values can be plain strings, but there is no magic or autoformatting...
# @var other_role_unset:example: other_role_unset: some_value
other_role_unset:
other_role_empty: ""
other_role_single: "b"
# @var demo_bool:example: $ false
demo_bool: true
# @var other_role_empty_dict:description: >
# ... or valid json can be used. In this case, the json will be automatically prefixed with the annotation key
# and filters like `to_nice_yaml` can be used in templates. To get it working, the json need to be prefixed with a `$`.
# @end
# @var other_role_empty_dict:example: $ {"key1": {"sub": "some value"}, "key2": {"sublist": ["subval1", "subval2"]}}
other_role_empty_dict: {}
# @var other_role_dict:example: >
# other_role_dict:
# key1:
# sub: some value
#
# # Inline description
# key2:
# sublist:
# - subval1
# - subval2
# @end
other_role_dict:
key1:
sub: some value
# @var other_role_undefined_var:description: >
# To highlight a variable that has not set a value by default, this is one way to achieve it.
# Make sure to flag it as json value: `@var other_role_undefined_var: $ "_unset_"`
#
# | Attribute | Description |
# | --- | --- |
# | value1 | desc1 |
#
# @end
# @var other_role_undefined_var: $ "_unset_"
# @var other_role_other_tags:description: >
# If a variable need some more explanation, this is a good place to do so.
# @end
# @var other_role_other_tags:example: $>
# [
# "package1",
# "package2"
# ]
# @end
# @var other_role_other_tags:value: $ ["package1", "package2"]
other_role_other_tags: []
## Simple value
# @var other_role_override: $ "test"
other_role_override: original
## Complex value
# @var other_role_override_complex:value: $ {"foo":"bar", "second":"value"}
other_role_override_complex: {}
# @var other_role_deprecated:deprecated:
other_role_deprecated: "b"
# @var other_role_deprecated_info:deprecated: >
# This variable is deprected since `v2.0.0` and will be removed in a future release.
# @var other_role_deprecated_info:type: string
other_role_deprecated_info: "a"
# @var other_role_multiline_type:type: >
# string
# list
# dict
# @end
other_role_multiline_type: "a"