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

Autogenerate Reference Documentation



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


      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?)


        Issue Links

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



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



                Gerrit Reviews

                  There are no open Gerrit changes