docs: combine API and CRD reference index pages into one

docs/docs/reference/api-reference/index.md

@@ -1,43 +1 @@
 # API Reference
-
-This section provides comprehensive reference information about all APIs
-that are defined In Keptn.
-This section is auto-generated from source code.
-
-Each CRD is an object of an API library.
-Keptn APIs follow the Kubernetes API versioning scheme.
-and are themselves composed of objects and sub-objects.
-The Keptn CRDs extend the base Kubernetes API
-with new objects and functionality.
-Keptn APIs follow API versioning conventions recommended by Kubernetes.
-
-Keptn generates most of the resources it needs
-without requiring manual input.
-[Lifecycle CRD Reference and Metrics CRD Reference](../crd-reference/index.md)
-contains reference pages for the manifests
-that must be populated manually.
-
-Use `kubectl` to inspect the current contents of any Keptn resource:
-
-1. List all resources of the specified type within a certain namespace.
-   For example, to list all the `KeptnApp` resources
-   in the `namespace1` namespace, the command is:
-
-        kubectl get keptnapps -n namespace1
-
-2. Get the current manifest for the specified resource.
-   For example, to view the manifest for the `my-keptn-app` resource
-   in the `namespace1` namespace, the command is:
-
-        kubectl get keptnapp -n <namespace> my-keptn-app -oyaml
-
-For more information about the APIs and Custom Resources,
-see the Kubernetes documentation:
-
-* [API Overview](https://kubernetes.io/docs/reference/using-api/)
-
-* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
-
-* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
-
-* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)

docs/docs/reference/crd-reference/index.md

@@ -1,21 +1 @@
 # CRD Reference
-
-This section provides comprehensive reference information about the
-manifest files that must be populated for Keptn
-[Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
-
-Each CRD is an object of an API library.
-In addition to the CRDs documented in this section,
-Keptn populates many resources on its own.
-For a comprehensive list of all Keptn resources, see
-[API Reference](../api-reference/index.md).
-
-For more information about CRDs and APIs, see the Kubernetes documentation:
-
-* [API Overview](https://kubernetes.io/docs/reference/using-api/)
-
-* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
-
-* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
-
-* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)

docs/docs/reference/index.md

@@ -1,11 +1,56 @@
 # Reference
 
-This section of the Keptn documentation contains reference documentation for the various APIs and CRDs that are used in Keptn.
+Welcome to the Keptn documentation reference section, your comprehensive guide to the various Custom Resource Definitions (CRDs) and APIs used in Keptn.
 
-If you want to learn more about specific Custom Resource Definitions
-that you may need to populate to use Keptn,
-go to the
-[CRD Reference](./crd-reference/index.md) section.
+## [CRD Reference](./crd-reference/index.md)
 
-If you want to look up some specific object properties or want ot know more about the internal APIs of Keptn,
-Go to the [API Reference](./api-reference/index.md) section.
+Dive into the manifest files crucial for Keptn—Custom Resource Definitions (CRDs).
+This section provides comprehensive reference information about the CRDs 
+that must be populated to tailor Keptn to your needs.
+
+Each CRD, an integral part of our API library, plays a crucial role in defining 
+the behavior of Keptn resources. While many resources are automatically populated,
+the CRD Reference guides you through the manual steps for specific manifests.
+
+For a comprehensive list of all Keptn resources, see the [API Reference](./api-reference/index.md).
+
+To learn more about CRDs, APIs, and Kubernetes objects, consult the Kubernetes documentation:
+
+* [API Overview](https://kubernetes.io/docs/reference/using-api/)
+* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
+* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)
+
+## [API Reference](./api-reference/index.md)
+
+Explore the rich set of APIs that Keptn offers, providing detailed
+information about all defined APIs. 
+This auto-generated content from source code offers insights into the structure,
+versioning, and functionality of Keptn APIs.
+
+Each API corresponds to an object in our API library, following Kubernetes API versioning.
+Keptn APIs extend the base Kubernetes API with additional objects and functionality. 
+Notably, Keptn generates many of its resources automatically, minimizing the need for manual input.
+
+For quick reference and practical usage, you can employ `kubectl` commands
+to inspect the current state of Keptn resources:
+
+1. **List all resources** of a specific type within a namespace. For example:
+
+    ```bash
+    kubectl get keptnapps -n namespace1
+    ```
+
+2. **Retrieve the current manifest** for a specified resource. For example:
+
+    ```bash
+    kubectl get keptnapp -n <namespace> my-keptn-app -oyaml
+    ```
+
+For further details on Kubernetes APIs, custom resources, versioning, and 
+understanding Kubernetes objects, refer to the Kubernetes documentation:
+
+* [API Overview](https://kubernetes.io/docs/reference/using-api/)
+* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
+* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)