Try to autogenerate Markdown Tables based on the comments from yaml.

values-yaml-doc.py

import argparse
import io
import itertools
import sys
from typing import Any, Generator, Tuple, Union

import ruamel
from pytablewriter import MarkdownTableWriter
from ruamel.yaml import YAML

yaml = YAML()
SEPARATOR = "."


def dict_flatten(data: dict) -> Generator[Tuple[str, Any], None, None]:
    def _dict_flatten(
        d: dict, parent_key: str = "", sep: str = SEPARATOR
    ) -> Generator[Tuple[str, Any], None, None]:
        for key, value in d.items():
            if isinstance(value, dict):
                yield from _dict_flatten(value, parent_key=f"{parent_key}{key}{sep}")
            else:
                yield (f"{parent_key}{key}", value)

    return _dict_flatten(data)


def list_flatten(data: list) -> list:
    def _list_flatten(l: list) -> Generator[Any, None, None]:
        for item in l:
            if isinstance(item, list):
                yield from _list_flatten(item)
            else:
                yield item

    return [item for item in _list_flatten(data) if item]


def path_into_list(path: str) -> list:
    return path.split(SEPARATOR)


def get_comment(data: Any, path: str) -> list:
    temp = data
    cas = []
    for key in path_into_list(path):
        temp = temp[key]
        if isinstance(temp, ruamel.yaml.comments.CommentedBase):
            cas.append(temp.ca.comment)
    return list_flatten(cas)


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("file", type=argparse.FileType("r"))
    parser.add_argument("--output", type=argparse.FileType("w"), default=sys.stdout)
    args = parser.parse_args()
    data = yaml.load(args.file)
    flatten_data = dict_flatten(data)
    new_data = {
        key: {
            "Parameter": key,
            "Default": value,
            "Description": " ".join(
                [
                    comment.value.replace("## ", "")
                    .replace("# ", "")
                    .replace("#", "")
                    .strip()
                    for comment in get_comment(data, key)
                ]
            ),
        }
        for key, value in flatten_data
    }
    headers = ["Parameter", "Description", "Default"]
    writer = MarkdownTableWriter(
        table_name="values.yaml",
        headers=headers,
        value_matrix=[
            [value[header] for header in headers] for value in new_data.values()
        ],
        margin=1,
    )
    writer.stream = args.output
    writer.write_table(flavor="github")