feat: add option for tabulating variables

[chipselden]

Description

Adding an configuration option which will render the Default Variables in a Markdown table rather than in separate sub-headings.

Usage

# .ansibledoctor.yml
template: readme
tabulate_variables: true

Notes

• The generated table dynamically determines which columns to include (i.e. if there are no variable "types" defined, there will be no Types column.
• | characters are escaped
• \n characters are converted into <br> characters
• The Table of Contents will not contain the list of variables if tabulate_variables is set to true
• This functionality was not added to the hugo-book template, but can be done so easily

Example

Defaults/main.yml

# defaults/main.yml
# @var join_the_dark_side:description: >
# Join the dark side, we have cookies
# @end
# @var join_the_dark_side:type: boolean
join_the_dark_side: true

# @var lighsaber_color:description: >
# The color of your lightsaber
# Options:
#   * red
#   * blue
#   * green
#   * purple
# @end
# @var lighsaber_color:type: string
lighsaber_color: red

# @var padawans:description: >
# List of padawans to train
# @end
# @var padawans:type: list(string)
padawans: []

Output

Text

| Variable | Default | Description | Type |
| -------- | ------- | ----------- | ---- |
| join_the_dark_side | True | Join the dark side, we have cookies | boolean |
| lighsaber_color | red | The color of your lightsaber<br>Options:<br> * red<br> * blue<br> * green<br> * purple | string |
| padawans | [] | List of padawans to train | list(string) |

Rendered

Variable	Default	Description	Type
join_the_dark_side	True	Join the dark side, we have cookies	boolean
lighsaber_color	red	The color of your lightsaber Options: * red * blue * green * purple	string
padawans	[]	List of padawans to train	list(string)

[rottj006]

Oh that's very compact, and easy to read, @xoxys will you be ok to make that output the default ?

[xoxys]

will you be ok to make that output the default ?

Mhm, I don't think so. That would be an (unnecessary) breaking change for users and quickly become difficult to read (e.g. long var names, descriptions, especially on small screens).

[xoxys]

@chipselden Thanks for your contribution! I'll need some time to look into it.

[chipselden]

@xoxys - Thanks, much appreciated!

[xoxys]

Just a few small findings so far. Would be cool if we can add it to the hugo-book template as well. We should also add documentation for the new config option.

[xoxys]

Sorry for the delay, I was on vacation. LGTM

[xoxys]

After some more tests, this approach IMO has some real disadvantages, especially if it comes to multiline strings and code blocks e.g. from more complex usage examples. I'll add a hint to the docs.

[chipselden]

Much appreciated, and I agree, it's not going to be the cleanest for every case, but could be nice in others. Thanks again!