CRD reference pages

[StackScribe]

Goal

A complete set of comprehensive reference pages that cover all KLT CRDs.
Eventually, these should be autogenerated from the software source code
but, until the tools are ready, we will draft them manually to figure out the
content and structure that works best.

Problem

Each CRD needs comprehensive documentation that is arranged for easy, randomized access. We address this in two ways:

• The API Reference section provides comprehensive information about each API.
  • This is auto-generated and comprehensive with minimal usage details required by novice users.
  • Some information can be embedded in the GO source file for the API libraries but we do not want to embed massive amounts of texts that make the source code unwieldy.
  • We will embed appropriate links to the CRD Reference pages
  • The API reference pages are arranged by library then by library version
  • The landing page for the API reference pages will include a brief explanation of the library versions and how they relate to KLT versions as well as a link to the k8s documentation about Kubernetes libraries.
• The CRD Reference section actually documents the YAML files that users populate to define their CRDs. Those YAML files may include files from the APIs that are sub-objects to the primary API. Each YAML file with which users interact has a reference page in this section that includes details and examples

Information to be included for each CRD reference page includes:

• Full synopsis of the CRD
• Detailed description of each field/parameter
• How this CRD is "activated" (for example, which event uses this CRD)
• Instructions and guidelines for when and how to customize a CRD
• Differences between versions
• See also links to examples and other documents that are relevant
• Initially, these pages will be arranged in a single list rather than being divided by library. The set of CRD YAML files that users see is much smaller than the full set of APIs so this should make the information accessible with one less click. After the initial set of pages are populated, we can review the presentation and decide if we prefer a different arrangement.
• ...

By consolidating this information, other documents can reference a CRD
and discuss components that are directly relevant to the subject at hand
and we do not end up with multiple guides and examples that attempt to provide
comprehensive information about the CRD and must be updated and sync'ed.

We will begin with one CRD per page, arranged alphabetically in one section.
We may eventually decide to group related CRDs in some way.

Initial structure has separate subdirectories for each API version. This may not be optimal; better to have each CRD documented on a single page that applies to all API versions, with notes about differences between API versions. We will begin by populating the current API version just to get the pages drafted. We can then evaluate whether to duplicate the info for each API version.

Technical Details

• Create CRD Reference section in the lifecycle-toolkit doc set
• Create a template for these pages that is stored in a file in that directory but marked hidden: true so it is excluded from builds
• Begin with the CRD information that is currently in the Getting Started Guide
• Identify where each CRD is defined in the source and then draft a page for each CRD, providing the information that is easily available.
  • This could be "good first issue" work.
  • Initially, we will manually copy/paste the synopsis information into the page although eventually this will be provided directly from the source
  • Gradually build up the quality of the content

DoD

• Phase 1 is complete when we have a page for each CRD currently defined with basic information (brief description, how it is activated, source file where it is defined, appropriate links to other docs and examples)
• Phase 2 is complete when we define how we want to actually structure this body of docs -- whether to leave as a single alphabetical list, create separate sections for groups of CRDs, or create pages that document multiple CRDs that are closely related) and then restructure the files accordingly
• Phase 3 is complete when we have tools in place to autogenerate these pages and have structured all content so that the autogenerated pages are complete.

Tasks

Preview Give feedback

1. Generate documentation from k8s CRDs #656
   enhancement good first issue +2
   
2. docs: [PoC] Draft of YAML oriented CRD ref page that is autogenerated (rejected) #1070
   documentation status: ready-for-refinement +2
   
3. Ref pages for KeptnTask* CRDs #1078
   documentation +1
   
4. Ref pages for KeptnApp* CRDs #1079
   documentation +1
   
5. "Concepts" ref pages for KeptnEvaluation* CRDs #1080
   documentation +1
6. "Concepts" ref pages for KeptnWorkload* CRDs #1081
   stale +1
7. Explain API versions in relationship to KLT versions #1118
   documentation stale +2
   
8. Ref pages for KeptnMetric CRD #1119
   documentation +1
   
9. Execution order for functionRef tasks #1124
   documentation stale +2
   
10. References to examples in source code #1143
    documentation stale +2
11. ref page for KeptnConfig #1238
    documentation +1
    
12. re-evaluate reference page structure and associated guide material #1381
    documentation stale +2
13. create section about secrets #1390
    documentation stale +2
14. Add xrefs between yaml-crd-ref pages and crd-ref pages #1465
    documentation good first issue stale +3

[StackScribe]

We have a good set of reference pages in place (https://main.lifecycle.keptn.sh/docs/yaml-crd-ref/ ) and can continue to improve and enhance them going forward.