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

Autogenerate Reference Documentation

    XMLWordPrintable

Details

    • Page
    • Status: Closed
    • Major
    • Resolution: Fixed
    • None
    • 2.2.0
    • documentation
    • None
    • 5

    Description

      K8S-1827, rather bluntly, deleted all the reference docs in favor, going forward, of online Kubernetes documentation.  This gives us:

      • Single source of truth for the docs (comments in the code)
      • Automatic addition/removal of attributes
      • Pads out the kubectl explain command before anyone raises a "defect"
      • 4,000 fewer lines to maintain, and it will send management crazy that we've removed code (mwuhaha)

      However, there are concerns that there is nowhere for things to link to now, and people have to install the software in order to read how to configure it.  To a lesser extent, you cannot just browse 2000 lines of reference docs (lol, as if).

      To allay those concerns, and keep all the positives, we need a solution.  And for now this looks like:

      • Trigger a CI job on commit to a branch
        • The technology to use here is somewhat dependent on the technical/security issues.  GitHub actions/Jenkins/etc.
      • Write a script that parses the CRD JSON, and emits asciidoc
        • Needs to filter out Kubernetes native data types or it will be gigantic (looking at you PodSpec)
      • Trawls the rest of the content and links resource attribute references to the auto generated reference docs.
        • Spotting broken links here is bad as the damage is already done, we need a CI job pre-commit to cross reference and reject shonky docs.
      • Commits the docs to a separate repository for use by the docs team
        • On a change only it goes without saying.
        • Would a public repo help here?  I know there have been problems in the past with private repos, but the downside is master now gives the game away to people who would follow it (why would you?)

      Attachments

        Issue Links

          For Gerrit Dashboard: K8S-1897
          # Subject Branch Project Status CR V

          Activity

            There are no comments yet on this issue.

            People

              simon.murray Simon Murray
              simon.murray Simon Murray
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:

                Gerrit Reviews

                  There are no open Gerrit changes

                  PagerDuty