Merge into existing README.md

[davidkarlsen]

Thanks for this great tool! It would be awesome if it could merge it's content into an existing README w/o overwriting the contents - a bit similar to how terraform-docs works - by placing a placeholder in the original README:

<!--- BEGIN_TF_DOCS --->

it replaces the block with its generated contents.

[norwoodj]

I have extensively used terraform-docs, and I like their idea here, but I decided to implement documentation generation using gotemplates. If you want to do what you describe, you can do the following:

cp README.md README.gotmpl

Add a section to the new file wherever you'd like docs to appear:

{{ template "chart.header" . }}
{{ template "chart.deprecationWarning" . }}

{{ template "chart.badgesSection" . }}

{{ template "chart.description" . }}

{{ template "chart.homepageLine" . }}

{{ template "chart.maintainersSection" . }}

{{ template "chart.sourcesSection" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}

then run:

helm-docs --template-files=./REAMDME.md.gotmpl

it should print the standard template to your README.md file.

If you'd like a simpler template rather than the 12 lines I've pasted above, I'm happy to implement that, but I like the gotemplate approach here and I'm not changing that particular implementation choice.

[HighWatersDev]

Hi, I'm trying to use .gotmpl file to merge the docs with the existing README but it's failing with the following error:

Error generating gotemplates for chart  chart:184: function "variables" not defined

I also looked under example-charts/custom-template and have it set up the same way but still getting the same error. I'm using helm-docs v1.8.1

[pecigonzalo]

Hey @norwoodj I know its an old issue, and I like this is using gotemplates, but I dont see that at odds with the request here. We can have something like

# Some title

some test

<!--- BEGIN_HELM_DOCS --->
{{ template "chart.header" . }}
{{ template "chart.deprecationWarning" . }}

{{ template "chart.badgesSection" . }}

{{ template "chart.description" . }}

{{ template "chart.homepageLine" . }}

{{ template "chart.maintainersSection" . }}

{{ template "chart.sourcesSection" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}
<!--- END_HELM_DOCS --->

[...]

That way we can still keep Markdown editing/highlight and etc for the content that is not managed by the generator.

[Nepo26]

Hey @pecigonzalo, how do you would this internal templating work? Below is the current behavior. Do you think it should be changed? If so, how do you propose should be the way?

If you have a Chart.yaml with the following info:

apiVersion: v2
appVersion: 1.16.0
description: A Helm chart for Kubernetes
name: Bob-Marley
version: 0.8.8

And a README.md as the following:

# Some title

Some test

{{ template "chart.header" . }}
{{ template "chart.deprecationWarning" . }}

{{ template "chart.badgesSection" . }}

{{ template "chart.description" . }}

{{ template "chart.homepageLine" . }}

{{ template "chart.maintainersSection" . }}

{{ template "chart.sourcesSection" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}

And ran this command that considers the README.md as a template:

helm-docs -t README.md .

The README.md file would be substituted by the following README, that I think is what is expected.

# Some title

Some test

# Bob-Marley

![Version: 0.8.8](https://img.shields.io/badge/Version-0.8.8-informational?style=flat-square) ![AppVersion: 1.16.0](https://img.shields.io/badge/AppVersion-1.16.0-informational?style=flat-square)

A Helm chart for Kubernetes

[pecigonzalo]

Hey @norwoodj sorry for the late reply. Something I oversaw is that Markdown format will not really care about {{ template }} so it will still be able to lint/parse it as valid Markdown, so that works.

how do you would this internal templating work? [...] If so, how do you propose should be the way?

Given a chart like

[...]
name: Bob-Marley
[...]

And a file like

# Some title

some test

{{ template "chart.header" . }}

<!--- BEGIN_HELM_DOCS --->
{{ template "chart.header" . }}
<!--- END_HELM_DOCS --->

[...]

Render

# Some title

some test

{{ template "chart.header" . }}

# Bob-Marley

[...]

Notice the {{ template "chart.header" . }} outside of the templating limits is not templated. We would need to extract the section between the template delimiters, template, replace it. Potentially there could be multiple sections even.

[Nepo26]

No problem @pecigonzalo.

Hmm, I guess it makes sense. The main takeaway would be to document something that uses {{ }} without interfering with it?! If so I can see it working.