Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Preserve formatting of examples #39

Open
very-doge-wow opened this issue Jul 20, 2022 · 1 comment
Open

Preserve formatting of examples #39

very-doge-wow opened this issue Jul 20, 2022 · 1 comment

Comments

@very-doge-wow
Copy link

very-doge-wow commented Jul 20, 2022

My chart has a bunch of features which can be activated through the values.yaml. Those however aren't just switches, but can contain templating themselves. As an example, one might pass a complete custom object definition as a string:

# Define a list of custom objects as complete k8s object definition (with template strings included).
# Example:
# customObjects:
#   - |
#     apiVersion: v1
#     kind: Secret
#     metadata:
#       name: best-token-{{ include "chart.fullname" . }}
#     type: Opaque
#     data:
#       mykey: {{ uuidv4 | sha256sum | b64enc }}
customObjects: []

First of all it's nice to have the example feature, where one can include an example inside the description field. Sadly the formatting isn't preserved, i.e. all whitespace at the start of each line is trimmed, so that the actual output looks more like this:

image

Which of course would be the wrong format if a user wants to copy that example as a reference. Also in general it's hard to read, as one can not be sure which elements belong to which yaml object.

So I would like to propose to keep the original formatting. Maybe you could even introduce a new flag like # Code-Example or similiar, which would then keep all the formatting done in the strings below it.
If possible, it would also be nice if that code example would be wrapped inside a single codeblock, not one for each line.

@very-doge-wow
Copy link
Author

Since the already existing tools for generating helm docs both do not possess the ability to maintain the pre-formatted example/default strings and there doesn't seem to be a lot of activity in these repositories, I've taken matters into my own hand and implemented yet another tool, which does preserve the formatting by default. Feel free to check it out:
https://github.com/very-doge-wow/stella

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant