Skip to content

Publish helm doc to hugo site#2006

Closed
MonkeyCanCode wants to merge 1 commit intoapache:mainfrom
MonkeyCanCode:public_helm_doc
Closed

Publish helm doc to hugo site#2006
MonkeyCanCode wants to merge 1 commit intoapache:mainfrom
MonkeyCanCode:public_helm_doc

Conversation

@MonkeyCanCode
Copy link
Contributor

@MonkeyCanCode MonkeyCanCode commented Jul 7, 2025 •
edited
Loading

The challenge with publishing helm doc to hugo site is the helm doc is outside of the content dir used by hugo (quick test with symbolic link doesn't appear to be working and hugo doesn't read the content from symbolic link). Thus, I am using mounts option from hugo to mount the current content into a virtual content then mount the relative path from helm chart README.md into the same virtual content but one directory under. By doing so, hugo is able to read this file without us duplicating the file.

One problem I see with this route is if we need to promo the current unreleased doc into <version> doc, we will need to duplicate the mounts entry such as following to allow same doc be read-able from both versions:

    # Mount from ../../polaris/helm/polaris into the virtual content/in-dev/unreleased/helm path
    - source: ../../polaris/helm/polaris
      target: content/in-dev/unreleased/helm
      excludeFiles: ["**"]
      includeFiles: ["README.md"]
    # Mount from ../../polaris/helm/polaris into the virtual content/in-dev/1.0.0/helm path
    - source: ../../polaris/helm/polaris
      target: content/in-dev/1.0.0/helm
      excludeFiles: ["**"]
      includeFiles: ["README.md"]

Also, as now we are trying to read chart's README file as web page, I had removed header as it will show duplicate header if we do so. Here is the rendered page with this solution:
image

@github-project-automation github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Jul 7, 2025
@MonkeyCanCode MonkeyCanCode mentioned this pull request Jul 7, 2025
Merged
dimas-b
dimas-b reviewed Jul 7, 2025
View reviewed changes
Copy link
Contributor

@dimas-b dimas-b left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The change LGTM, but I wonder if @snazy has any feedback regarding the versioned docs workflow.

@dimas-b dimas-b requested a review from snazy July 7, 2025 23:33
@snazy
Copy link
Member

snazy commented Jul 8, 2025

I wonder whether it's not easier to just copy the README.md file from helm/polaris to site/content/in-dev/unreleased when it's generated.
The workflow for releases is to take what's in site/content/in-dev/unreleased and push it to the versioned-docs branch. With a virtual mount, the helm readme would not be present.

Orthogonal to this PR, I realized that the Helm README.md is generated, but there's nothing that guarantees that the file is up to date. I think, it would be better to not track the generated README.md in Git or at least have a CI step that verifies that the README.md file is up to date (aka generate in CI and compare with the one in Git). WDYT?

@adutra
Copy link
Contributor

adutra commented Jul 8, 2025

realized that the Helm README.md is generated, but there's nothing that guarantees that the file is up to date. I think, it would be better to not track the generated README.md in Git or at least have a CI step that verifies that the README.md file is up to date (aka generate in CI and compare with the one in Git).

+1. The only reason to have that generated README.md file committed in Git was to allow users to read the Helm docs when browsing the GitHub repo. A CI check to enforce that it's in sync with the template would be nice.

@MonkeyCanCode
Copy link
Contributor Author

MonkeyCanCode commented Jul 9, 2025 •
edited
Loading

realized that the Helm README.md is generated, but there's nothing that guarantees that the file is up to date. I think, it would be better to not track the generated README.md in Git or at least have a CI step that verifies that the README.md file is up to date (aka generate in CI and compare with the one in Git).

+1. The only reason to have that generated README.md file committed in Git was to allow users to read the Helm docs when browsing the GitHub repo. A CI check to enforce that it's in sync with the template would be nice.

Great. So everyone agreed we will just copy file (automate it as part of the CI). I will close this for now then raise two separate PRs for adding the one time doc then another PR for the automation. I have some ideas on what we can do to streamline those processes and I will raise an PR with sample workflow to get more feedback on the purposed workflow soon.

@github-project-automation github-project-automation bot moved this from PRs In Progress to Done in Basic Kanban Board Jul 9, 2025
@MonkeyCanCode MonkeyCanCode mentioned this pull request Jul 9, 2025
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dimas-b dimas-b dimas-b left review comments

@snazy snazy Awaiting requested review from snazy

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@MonkeyCanCode @snazy @adutra @dimas-b