abrisco
Root README.md should link to documentation of the rules
A lot of the Markdown boilerplate can be generated: http://skydoc.bazel.build
Doesn't it already do that? https://github.com/abrisco/rules_helm/blob/58640819f1bd6e9e74b27675fa16814562302cb4/README.md
The only thing I find linked from there makes no mention of anything in the .bzl files and just describes how to use @rules_helm//helm:current_toolchain and $(HELM_BIN) in a genrule() strongly implying that those rules don't exist.
A bit of hunting around and it looks like all the docs are in an obscure and unrelated branch as HTML which seems like a great way for them to go unnoticed.
Even better than the README.md linking to the docs for the rules would be if the docs for the rules were directly inline in README.md on the main branch. Then user don't even need to leave the root page to find them and can even browse them in their IDE while working with the code being documented.
The reason I link to a separate site is because it can be auto generated and there's no overhead for making sure the README is up to date with some generated content. If you think there's a better way to handle docs I'd be happy to review a PR :) I definitely want rendered docs and this was the trade I landed on between maintainability and readability.
There are some bazel rules that combine generated content with a test to check that the content matches a checked in file and a bazel run rule that updates that same file. If you enable a pre-commit or CI to guard main on test passing that would 1) enforce updating the docs, 2) make updating them easy and 3) make updating them locally without a push simple as well.
Also, I eventually found what you were intending that link to point at: the other page at github.io which is the only one that has anything I'm interested in.
Suggestion: if you chose to continue with the docs being out-of-line, either (in decreasing order of preference):
- Combine all the content into a single page (unless it takes a noticeable amount of time to load, the page isn't too big).
- Update the README link to point at the other page with the thing people are actually expected to use.
- Choose a template that makes it a lot more clear that there is other content. The current template makes it looks like there is one page ("Rules") that is already being show rather than there being two pages and the current page is the "Introduction" (despite the in page title being "rules_helm").