Skip to content

Publish helm doc #2014

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

Merged
merged 1 commit into from
Jul 11, 2025
Merged

Publish helm doc #2014

merged 1 commit into from
Jul 11, 2025

Conversation

MonkeyCanCode
Copy link
Contributor

This PR does one time publication of helm doc into hugo. As discussed in #2006, we will enable automation for this workflow in the following PR.

@flyrain
Copy link
Contributor

flyrain commented Jul 11, 2025

LGTM
Not a blocker: I'm just a bit concern about the sync between two directories. Is it OK to not have a README within helm/Polaris, or just have a dummy one without worrying about maintenance? Then we can focus on the the doc in the site.

@github-project-automation github-project-automation bot moved this from PRs In Progress to Ready to merge in Basic Kanban Board Jul 11, 2025
@MonkeyCanCode
Copy link
Contributor Author

LGTM
Not a blocker: I'm just a bit concern about the sync between two directories. Is it OK to not have a README within helm/Polaris, or just have a dummy one without worrying about maintenance? Then we can focus on the the doc in the site.

Understand. Yes, I should have time to get some automation up for those. The reason why we will have a file there within the helm repo is due to helm-doc rendering. So technically, we can save output to the site and keep the template there. This will then be done via a pre-commit hook.

@MonkeyCanCode MonkeyCanCode merged commit ccc97bf into apache:main Jul 11, 2025
11 checks passed
@github-project-automation github-project-automation bot moved this from Ready to merge to Done in Basic Kanban Board Jul 11, 2025
@flyrain
Copy link
Contributor

flyrain commented Jul 11, 2025

The reason why we will have a file there within the helm repo is due to helm-doc rendering.

I'm not quite familiar with Helm use cases. Do helm end users really care about helm-doc rendering? If not, we could just leave an empty template there.

@MonkeyCanCode
Copy link
Contributor Author

The reason why we will have a file there within the helm repo is due to helm-doc rendering.

I'm not quite familiar with Helm use cases. Do helm end users really care about helm-doc rendering? If not, we could just leave an empty template there.

I personally do think helm docs are useful as people can quickly find the settings/values and understand what configuration options exists without going through length values.yaml used by the chart. It is quite common to populate the helm doc for a chart (e.g. https://artifacthub.io/packages/helm/grafana/grafana), however, it is a not a requirement for a helm chart. If the public doc only wants to includes steps on how to install/remove the chart, then this is an overkill for sure.

@flyrain
Copy link
Contributor

flyrain commented Jul 11, 2025

I think we on the same page. It's great to have doc for Helm for sure, but maintaining two exact copies isn't. One option is having the complete doc page in Polaris website only, and to add a link in the file helm/polaris/README.md pointing to the page.

@MonkeyCanCode
Copy link
Contributor Author

MonkeyCanCode commented Jul 11, 2025

I think we on the same page. It's great to have doc for Helm for sure, but maintaining two exact copies isn't. One option is having the complete doc page in Polaris website only, and to add a link in the file helm/polaris/README.md pointing to the page.

Yes. We can do that. I tried a symbolic link from the helm to hugo dir and that didn't go well (seems to be some limitations with Hugo). But for sure we can generate the doc under site and symbolic back to the helm chart (or figure out why Hugo doesn't like the symbolic link in the first place). I added a sample workflow in #2027 to address the duplicate README file issue (in this case, it is still copy and paste based on feedback from the communities, but we can for sure change to the symbolic link route and update the workflow to generate file to the site location instead)

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

Successfully merging this pull request may close these issues.

2 participants