Conversation
|
Screenshot of the values reference page: 
|
adutra
force-pushed
the
helm-docs-overhaul2
branch
2 times, most recently
from
217212c to
2b0b30a
Compare
|
|
||
| ## Documentation | ||
|
|
||
| - **[Production Installation]({{% relref "production" %}})**: Instructions for deploying Polaris in a production environment, including how to add the Helm repository and set up scaling. |
There was a problem hiding this comment.
does relref work inside the multi-version docs build? I remember seeing some odd issues related to using the same link name in multiple doc versions... but I do not recall exactly 😅
There was a problem hiding this comment.
I deployed the Hugo site locally and everything is working. Should I do some more checks?
There was a problem hiding this comment.
It's fine... I do not remember the exact old error anyway 😅 we can fix when/if it breaks again.
github-project-automation
bot
moved this from PRs In Progress
to Ready to merge
in Basic Kanban Board
adutra
force-pushed
the
helm-docs-overhaul2
branch
2 times, most recently
from
e67901a to
612f7fd
Compare
|
Thanks for the PR @adutra . This looks very clean and a lot better than the original length doc. The new added section annotations is great for helping new users to get familiar with the values file. I left couple comments. Overall, looks good to me. |
| | realmContext.type | string | `"default"` | The type of realm context resolver to use. Two built-in types are supported: default and test; test is not recommended for production as it does not perform any realm validation. | | ||
| | realmContext.realms | list | `["POLARIS"]` | List of valid realms, for use with the default realm context resolver. The first realm in the list is the default realm. Realms not in this list will be rejected. | | ||
|
|
||
| ### Features |
There was a problem hiding this comment.
nit: this section may looks odd to new users i think as the only value we have is features.realmOverrides and all other features are from default application config.
There was a problem hiding this comment.
True, let me try to improve this.
There was a problem hiding this comment.
Not sure what should we do here? Put some default values here to make this section more read-able for end-users? But if we do so, we will then need to maintain the full list of default values going forward.
There was a problem hiding this comment.
@MonkeyCanCode I came up with a different approach: I switched to HTML rendering for the docs, which allows me to easily include examples in the documentation.
There is one drawback though: the examples need to be written in HTML and they appear as (garbled) HTML content inside the JSON schema file.
Let me know what you think!
There was a problem hiding this comment.
This is really interesting route and something that I didn't know that is possible to do. IMO, having sample values is more user friendly if the end-users is only looking at the site and not looking at the values file. However, it does appears this add good amount of potential overhead to the values file as you mentioned above (also seeing html tags in values file appear to be a bit overwhelming for the first impression and make the values file a bit more harder to read IMO). Based on my experiences, I spent way more time reading values files as opposed to checking the rendered values files on browser. I am not sure if this is truly worth it for this potential overhead or user experience. As this really only apply to one configuration, perhaps we should just pick a default enabled feature and have it not commented out such as
polaris.features."SUPPORTED_CATALOG_STORAGE_TYPES" = [ "S3", "Azure", "GCP", "FILE"]
Plus, we already have document in-placed for production configuration to warm user to turn off the FILE one for this config). Thoughts?
There was a problem hiding this comment.
I agree with you, it was a bit too much. I partially reverted the changes and went back to markdown tables.
I also added an example for polaris.features but the example I added was: polaris.features."SUPPORTED_CATALOG_STORAGE_TYPES" = [ "S3", "Azure", "GCP"] without FILE since that is the default value for this flag.
Let me know what you think!
There was a problem hiding this comment.
The helm-docs project has an issue open for adding support for an Example column:
I may try to contribute that feature.
adutra
force-pushed
the
helm-docs-overhaul2
branch
5 times, most recently
from
01a21a5 to
2ed12c0
Compare
This PR completely redesigns the Helm chart docs, and breaks the existing doc page into several pages: Production, Persistence, Authentication, Networking, Development, and Reference. The values reference page contains the generated helm-docs output, but it is now split into many sections for readability. Non-leaf nodes in values.yaml file are now excluded from the generated output because they tend to produce unreadable content.
adutra
force-pushed
the
helm-docs-overhaul2
branch
from
2ed12c0 to
213fcb0
Compare
github-project-automation
bot
moved this from Ready to merge
to Done
in Basic Kanban Board
|
Thanks @MonkeyCanCode for the thorough review and many nice suggestions! 🙏 |
3 participants
This PR completely redesigns the Helm chart docs, and breaks the existing doc page into several pages: Production, Persistence, Authentication, Networking, Development, and Reference.
The values reference page contains the generated helm-docs output, but it is now split into many sections for readability. Non-leaf nodes in values.yaml file are now excluded from the generated output because they tend to produce unreadable content.
Screenshot of the new chart landing page:
Checklist
CHANGELOG.md(if needed)site/content/in-dev/unreleased(if needed)