Uploaded image for project: 'Couchbase Kubernetes'
  1. Couchbase Kubernetes
  2. K8S-1991

Helm Doc Auto-generation PART 1: The Beginning

    XMLWordPrintable

Details

    • Page
    • Status: Closed
    • Major
    • Resolution: Done
    • None
    • 2.2.0
    • documentation, helm
    • None
    • 1

    Description

      K8S-1897 introduced tools and a workflow to auto-generate reference documentation for custom resources. We should introduce a similar process for the Helm reference documentation.

      Currently, there is only one Helm-related reference page, and it documents the values.yaml spec. The page format is very similar to that of the custom resource pages that are generated by K8S-1897 (because they're effectively documenting the same fields and parameters).

      The following should be considered when building an auto-generation workflow for Helm reference docs:

      1. If the fields in values.yaml are basically already documented in the reference for the other custom resource (e.g. couchbasecluster, coubasebucket, couchbaseuser, etc.) then should we try and import that content automatically instead of writing duplicate descriptions for the Helm reference?
      2. Can/should the Helm reference docs be generated in the Operator repo? It seems that this would be ideal and would require the least amount of re-tooling.
      3. The existing values.yaml has some in-line documentation. Should preserve this separately from the documentation we write for the standard docs set? And can these docs be read from kubectl/helm command-line?

      Attachments

        Issue Links

          No reviews matched the request. Check your Options in the drop-down menu of this sections header.

          Activity

            Per discussion in Mar 3, Tommie is looking to this.

            ingenthr Matt Ingenthron added a comment - Per discussion in Mar 3, Tommie is looking to this.

            Could you please summarize what we tried here in the comments, good notes so we know where to pick it up in the future if we can please. Then move to not-targeted.

            ingenthr Matt Ingenthron added a comment - Could you please summarize what we tried here in the comments, good notes so we know where to pick it up in the future if we can please. Then move to not-targeted.

            We'll need to create a Page ticket to track the manual doc updates (if one hasn't been created).

            eric.schneider Eric Schneider (Inactive) added a comment - We'll need to create a Page ticket to track the manual doc updates (if one hasn't been created).

            We have something going now, it's by no means anywhere near perfect but is functional.

            patrick.stephens Patrick Stephens (Inactive) added a comment - We have something going now, it's by no means anywhere near perfect but is functional.

            The first iteration of auto-generation was checked in with K8S-2120. The auto-generated content is being reviewed in K8S-2033.

            A follow-up ticket, K8S-2186, was created to handle further refinement of the auto-generation content and format.

            eric.schneider Eric Schneider (Inactive) added a comment - The first iteration of auto-generation was checked in with K8S-2120 . The auto-generated content is being reviewed in K8S-2033 . A follow-up ticket, K8S-2186 , was created to handle further refinement of the auto-generation content and format.

            People

              simon.murray Simon Murray
              eric.schneider Eric Schneider (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:

                Gerrit Reviews

                  There are no open Gerrit changes

                  PagerDuty