docs: [PoC] Draft of YAML oriented CRD ref page that is autogenerated (rejected)

[StackScribe]

DO NOT MERGE THIS EVER!!! IT INCLUDES pseudo-ish code that does not build.

This is based on the following existing documentation:

• Concepts/Keptn Task Definition
• Auto-generated reference page for KeptnTaskDefinition

We want auto-generated reference pages but we need additional content to make them interesting and useful to users. This requires adding authored content to the autogenerated content. The user sees a CRD mostly as the yaml file they must create. The authored content should be co-located with the source code to make it easy for developers to identify when source code changes necessitate doc modifications.

This is a mock-up of the structure and content I propose. I think it gives the user the information they need and a format that allows us to easily add information as we see what information users need. This augments the current auto-generated pages as follows:

• Many more subsections on the page with additional text
• Each CRD gets its own page. Advantages:
  • Easier for users to find
  • Easier to reference from other docs in the set
  • Source file is much more manageable --
    adding this amount of content for all CRDs in the existing library file would make for an unwieldy file.

Some tools work is required to support this amount of markdown formatting in a go file. That is a separate discussion and it is possible that we will find out that it is not possible to implement this design. But the purpose of this exercise is to agree about what we want.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

No Coverage information
0.0% Duplication

[netlify]

✅ Deploy Preview for keptn-lifecycle-toolkit ready!

Name	Link
🔨 Latest commit	14d645e
🔍 Latest deploy log	https://app.netlify.com/sites/keptn-lifecycle-toolkit/deploys/6417c2fb8b1c29000868f700
😎 Deploy Preview	https://deploy-preview-1070--keptn-lifecycle-toolkit.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[StackScribe]

We discussed this at the 22 March [Keptn Refinement Meeting]. Conclusions were:

• All this authored text inside the source code is unwieldy!
• API Ref should be very technical and this will make sense to developers, who are most of our audience
• It would be very difficult to have the auto-generated text spit out separate files for each CRD
• Inserting this amount of authored text inside the source code is far more onerous than just writing markdown files in the docs source tree

Recommended actions:

• Meg will turn the "Concepts" section into a reference section, with a page for each CRD that focuses on the YAML syntax and explains the fields in some detail, using the same structure proposed in this PoC
• Each "Concepts" reference page will include a link to the relevant API Ref
• The API Ref source code will include comment lines that link to the relevant "Concepts" page
• The title and placement of the "Concepts" section may be changed later but this approach lets us create the content; modifications can be implemented easily at a later time.