Merge pull request #45496 from dipesh-rawat/api-ref-link-shortcode

k8s-ci-robot · web-flow · commit f089d6debccc · 2024-03-31T19:25:34.000-07:00
Add mechanism to retrieve API reference page link based on metadata
diff --git a/content/en/docs/concepts/architecture/leases.md b/content/en/docs/concepts/architecture/leases.md
@@ -1,5 +1,8 @@
 ---
 title: Leases
+api_metadata:
+- apiVersion: "coordination.k8s.io/v1"
+  kind: "Lease"
 content_type: concept
 weight: 30
 ---
diff --git a/content/en/docs/concepts/architecture/nodes.md b/content/en/docs/concepts/architecture/nodes.md
@@ -3,6 +3,9 @@ reviewers:
 - caesarxuchao
 - dchen1107
 title: Nodes
+api_metadata:
+- apiVersion: "v1"
+  kind: "Node"
 content_type: concept
 weight: 10
 ---
diff --git a/content/en/docs/concepts/configuration/configmap.md b/content/en/docs/concepts/configuration/configmap.md
@@ -1,5 +1,8 @@
 ---
 title: ConfigMaps
+api_metadata:
+- apiVersion: "v1"
+  kind: "ConfigMap"
 content_type: concept
 weight: 20
 ---
diff --git a/content/en/docs/concepts/configuration/secret.md b/content/en/docs/concepts/configuration/secret.md
@@ -2,6 +2,9 @@
 reviewers:
   - mikedanese
 title: Secrets
+api_metadata:
+- apiVersion: "v1"
+  kind: "Secret"
 content_type: concept
 feature:
   title: Secret and configuration management
diff --git a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md
@@ -3,6 +3,9 @@ title: Custom Resources
 reviewers:
 - enisoc
 - deads2k
+api_metadata:
+- apiVersion: "apiextensions.k8s.io/v1"
+  kind: "CustomResourceDefinition"
 content_type: concept
 weight: 10
 ---
diff --git a/content/en/docs/concepts/overview/working-with-objects/namespaces.md b/content/en/docs/concepts/overview/working-with-objects/namespaces.md
@@ -4,6 +4,9 @@ reviewers:
 - mikedanese
 - thockin
 title: Namespaces
+api_metadata:
+- apiVersion: "v1"
+  kind: "Namespace"
 content_type: concept
 weight: 45
 ---
diff --git a/content/en/docs/concepts/policy/limit-range.md b/content/en/docs/concepts/policy/limit-range.md
@@ -2,6 +2,9 @@
 reviewers:
 - nelvadas
 title: Limit Ranges
+api_metadata:
+- apiVersion: "v1"
+  kind: "LimitRange"
 content_type: concept
 weight: 10
 ---
diff --git a/content/en/docs/concepts/policy/resource-quotas.md b/content/en/docs/concepts/policy/resource-quotas.md
@@ -2,6 +2,9 @@
 reviewers:
 - derekwaynecarr
 title: Resource Quotas
+api_metadata:
+- apiVersion: "v1"
+  kind: "ResourceQuota"
 content_type: concept
 weight: 20
 ---
diff --git a/content/en/docs/concepts/services-networking/endpoint-slices.md b/content/en/docs/concepts/services-networking/endpoint-slices.md
@@ -2,6 +2,9 @@
 reviewers:
 - freehan
 title: EndpointSlices
+api_metadata:
+- apiVersion: "discovery.k8s.io/v1"
+  kind: "EndpointSlice"
 content_type: concept
 weight: 60
 description: >-
diff --git a/content/en/docs/concepts/services-networking/ingress.md b/content/en/docs/concepts/services-networking/ingress.md
@@ -2,6 +2,11 @@
 reviewers:
 - bprashanth
 title: Ingress
+api_metadata:
+- apiVersion: "networking.k8s.io/v1"
+  kind: "Ingress"
+- apiVersion: "networking.k8s.io/v1"
+  kind: "IngressClass"  
 content_type: concept
 description: >-
   Make your HTTP (or HTTPS) network service available using a protocol-aware configuration
diff --git a/content/en/docs/concepts/services-networking/service.md b/content/en/docs/concepts/services-networking/service.md
@@ -2,6 +2,9 @@
 reviewers:
 - bprashanth
 title: Service
+api_metadata:
+- apiVersion: "v1"
+  kind: "Service"
 feature:
   title: Service discovery and load balancing
   description: >
diff --git a/content/en/docs/concepts/storage/persistent-volumes.md b/content/en/docs/concepts/storage/persistent-volumes.md
@@ -6,6 +6,9 @@ reviewers:
 - msau42
 - xing-yang
 title: Persistent Volumes
+api_metadata:
+- apiVersion: "v1"
+  kind: "PersistentVolume"
 feature:
   title: Storage orchestration
   description: >
diff --git a/content/en/docs/concepts/storage/volumes.md b/content/en/docs/concepts/storage/volumes.md
@@ -5,6 +5,9 @@ reviewers:
 - thockin
 - msau42
 title: Volumes
+api_metadata:
+- apiVersion: ""
+  kind: "Volume"
 content_type: concept
 weight: 10
 ---
diff --git a/content/en/docs/concepts/workloads/controllers/cron-jobs.md b/content/en/docs/concepts/workloads/controllers/cron-jobs.md
@@ -4,6 +4,9 @@ reviewers:
 - soltysh
 - janetkuo
 title: CronJob
+api_metadata:
+- apiVersion: "batch/v1"
+  kind: "CronJob"
 content_type: concept
 description: >-
   A CronJob starts one-time Jobs on a repeating schedule.
diff --git a/content/en/docs/concepts/workloads/controllers/daemonset.md b/content/en/docs/concepts/workloads/controllers/daemonset.md
@@ -6,6 +6,9 @@ reviewers:
 - janetkuo
 - kow3ns
 title: DaemonSet
+api_metadata:
+- apiVersion: "apps/v1"
+  kind: "DaemonSet"
 description: >-
  A DaemonSet defines Pods that provide node-local facilities. These might be fundamental to the operation of your cluster, such as a networking helper tool, or be part of an add-on.
 content_type: concept
diff --git a/content/en/docs/concepts/workloads/controllers/deployment.md b/content/en/docs/concepts/workloads/controllers/deployment.md
@@ -2,6 +2,9 @@
 reviewers:
 - janetkuo
 title: Deployments
+api_metadata:
+- apiVersion: "apps/v1"
+  kind: "Deployment"
 feature:
   title: Automated rollouts and rollbacks
   description: >
diff --git a/content/en/docs/concepts/workloads/controllers/job.md b/content/en/docs/concepts/workloads/controllers/job.md
@@ -4,6 +4,9 @@ reviewers:
 - erictune
 - soltysh
 title: Jobs
+api_metadata:
+- apiVersion: "batch/v1"
+  kind: "Job"
 content_type: concept
 description: >-
   Jobs represent one-off tasks that run to completion and then stop.
diff --git a/content/en/docs/concepts/workloads/controllers/replicaset.md b/content/en/docs/concepts/workloads/controllers/replicaset.md
@@ -4,6 +4,9 @@ reviewers:
 - bprashanth
 - madhusudancs
 title: ReplicaSet
+api_metadata:
+- apiVersion: "apps/v1"
+  kind: "ReplicaSet"
 feature:
   title: Self-healing
   anchor: How a ReplicaSet works
diff --git a/content/en/docs/concepts/workloads/controllers/replicationcontroller.md b/content/en/docs/concepts/workloads/controllers/replicationcontroller.md
@@ -3,6 +3,9 @@ reviewers:
 - bprashanth
 - janetkuo
 title: ReplicationController
+api_metadata:
+- apiVersion: "v1"
+  kind: "ReplicationController"
 content_type: concept
 weight: 90
 description: >-
diff --git a/content/en/docs/concepts/workloads/controllers/statefulset.md b/content/en/docs/concepts/workloads/controllers/statefulset.md
@@ -7,6 +7,9 @@ reviewers:
 - kow3ns
 - smarterclayton
 title: StatefulSets
+api_metadata:
+- apiVersion: "apps/v1"
+  kind: "StatefulSet"
 content_type: concept
 description: >-
   A StatefulSet runs a group of Pods, and maintains a sticky identity for each of those Pods. This is useful for managing
diff --git a/content/en/docs/concepts/workloads/pods/_index.md b/content/en/docs/concepts/workloads/pods/_index.md
@@ -2,6 +2,9 @@
 reviewers:
 - erictune
 title: Pods
+api_metadata:
+- apiVersion: "v1"
+  kind: "Pod"
 content_type: concept
 weight: 10
 no_list: true
diff --git a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md
@@ -5,6 +5,12 @@ reviewers:
 - munnerz
 - enj
 title: Certificates and Certificate Signing Requests
+api_metadata:
+- apiVersion: "certificates.k8s.io/v1"
+  kind: "CertificateSigningRequest"
+  override_link_text: "CSR v1"
+- apiVersion: "certificates.k8s.io/v1alpha1"
+  kind: "ClusterTrustBundle"  
 content_type: concept
 weight: 25
 ---
@@ -608,3 +614,5 @@ kubectl config use-context myuser
 * View the source code for the kube-controller-manager built in [approver](https://github.com/kubernetes/kubernetes/blob/32ec6c212ec9415f604ffc1f4c1f29b782968ff1/pkg/controller/certificates/approver/sarapprove.go)
 * For details of X.509 itself, refer to [RFC 5280](https://tools.ietf.org/html/rfc5280#section-3.1) section 3.1
 * For information on the syntax of PKCS#10 certificate signing requests, refer to [RFC 2986](https://tools.ietf.org/html/rfc2986)
+* Read about the ClusterTrustBundle API:
+  * {{< page-api-reference kind="ClusterTrustBundle" >}}
diff --git a/data/i18n/en/en.toml b/data/i18n/en/en.toml
@@ -3,6 +3,9 @@
 
 # For "and", see [conjunction_1]
 
+[api_reference_title]
+other = "API reference"
+
 [auto_generated_edit_notice]
 other = "(auto-generated page)"
 
diff --git a/layouts/docs/list.html b/layouts/docs/list.html
@@ -17,6 +17,8 @@
             {{ partial "docs/top-section-page" (dict "ctx" $ "page" $ ) }}
             {{- else -}}
             {{ partial "docs/content-page" (dict "ctx" $ "page" $ ) }}
+            <!-- Partial "docs/api-reference-links" determines API reference links for 'partial/page-meta-links.html' -->
+            {{ partial "docs/api-reference-links" $ }}
             {{- end -}}
         {{ else }}
             <h1>{{ .Title }}</h1>
diff --git a/layouts/docs/single.html b/layouts/docs/single.html
@@ -1,6 +1,8 @@
 {{ define "main" }}
     <div class="td-content">
     {{ partial "docs/content-page" (dict "ctx" . "page" .) }}
+    <!-- Partial "docs/api-reference-links" determines API reference links for 'partial/page-meta-links.html' -->
+    {{ partial "docs/api-reference-links" . }}
     </div>
 {{ end }}
 {{ define "hero-more" }}
diff --git a/layouts/partials/docs/api-reference-links.html b/layouts/partials/docs/api-reference-links.html
@@ -0,0 +1,58 @@
+<!-- Define slice to store API reference links -->
+{{- $apiReferenceMetaLinks := slice -}}
+{{- $apiReferenceText := T "api_reference_title" -}}
+
+<!-- Clear exisiting $.Store values --> 
+{{ $.Store.Delete "apiReferenceMetaLinks" }}
+{{ $.Store.Delete "pageApiReferenceLinksMap" }}
+
+<!-- Check if 'api_metadata' is an empty interface slice 
+    (Used for excluding auto-generated files and their localized versions) -->
+{{- $ignoreCondition := (printf "%T" .Page.Params.api_metadata | eq "[]interface {}") -}}
+
+<!-- Check if 'api-metadata' exists in the front-matter of the file -->
+{{- if and .Page.Params.api_metadata $ignoreCondition (not .Page.Params.simple_list) -}}
+
+    <!-- Loop through each api_metadata entry -->
+    {{- range $metadata := .Page.Params.api_metadata -}}
+    <!-- Extract API metadata -->
+    {{- $apiVersion := $metadata.apiVersion -}}
+    {{- $kind := $metadata.kind -}}
+    {{- $version := $apiVersion -}}
+    {{- $linkText := $metadata.override_link_text  | default $kind -}}
+    
+    <!-- Get all sections under the specified directory -->
+    {{- $apiRefBaseDir := "docs/reference/kubernetes-api/" -}}
+    {{- $apiRefSections := site.GetPage "section" $apiRefBaseDir -}}
+
+    <!-- Loop through sections -->
+    {{- range $apiRefSection := $apiRefSections.Sections -}}
+        {{- $apiRefDir := $apiRefSection.RelPermalink -}}
+        {{- $apiReferenceFiles := site.GetPage $apiRefDir -}}
+
+        <!-- Loop through API reference files -->
+        {{- range $apiRefFile := $apiReferenceFiles.RegularPages -}}
+        {{- $apiRefFileDirPath:= printf "/%s" $apiRefFile.File.Dir -}}
+
+        {{- if and (ne $apiRefFile.Section "") (in $apiRefFileDirPath $apiRefDir) -}}
+            <!-- Check if the file's metadata matches -->
+            {{- with $apiRefFile.Params.api_metadata -}}
+            {{- if and (eq .kind $kind) (eq .apiVersion $version) -}}
+                <!-- If the file's metadata matches, add link to variable -->
+                {{- $link := printf "<a class='api-reference-page-link' href='%s'>%s %s</a>" $apiRefFile.Permalink $linkText $apiReferenceText -}}
+                {{- $apiReferenceMetaLinks = $apiReferenceMetaLinks | append $link -}}
+                <!-- Add to the map -->
+                {{- $.Store.SetInMap "pageApiReferenceLinksMap" $kind $link -}}
+            {{- end -}}
+            {{- end -}}
+        {{- end -}}
+        {{- end -}}
+    {{- end -}}
+    {{- end -}}
+{{- end -}}
+
+{{- if gt (len $apiReferenceMetaLinks) 0 -}}
+    <!-- Store $apiReferenceMetaLinks for meta links in 'partials/page-meta-links.html' -->
+    {{ $.Store.Add "apiReferenceMetaLinks" $apiReferenceMetaLinks }}
+{{- end -}}
+
diff --git a/layouts/partials/page-meta-links.html b/layouts/partials/page-meta-links.html
@@ -23,6 +23,16 @@
     {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL }}
     {{ $newPageURL := printf "%s/new/%s?%s"  $gh_repo $gh_repo_path $newPageQS }}
 
+    <!-- Accessing API Reference links from "layouts/api-reference-links.html" -->
+    {{- $apiReferenceMetaLinks := $.Store.Get "apiReferenceMetaLinks" -}}
+    {{- if $apiReferenceMetaLinks -}}
+      <!-- Loop through the API reference links -->
+        {{- range $apiReferenceMetaLinks -}}
+          {{- $apiRefPageLink  := . -}}
+          {{- $apiRefPageLink  | replaceRE "<a([^>]*)>" "<a$1><i class=\"fa fa-code fa-fw\"></i> " | safeHTML -}}
+        {{- end -}}
+    {{- end -}}
+
     {{ if not (.Param "auto_generated") }}
     <a href="{{ $editURL }}" target="_blank"><i class="fa fa-edit fa-fw"></i> {{ T "post_edit_this" }}</a>
     {{- if .HasShortcode "thirdparty-content" -}}
diff --git a/layouts/shortcodes/page-api-reference.html b/layouts/shortcodes/page-api-reference.html
@@ -0,0 +1,32 @@
+<!-- This shortcode shows API reference links based on metadata in the page's front matter -->
+ 
+<!-- Call the partial template "docs/api-reference-links" to determine the API reference links -->
+{{ partial "docs/api-reference-links" page }}
+
+ <!-- "noop" (“no operation”) statement to let content render and store sync -->
+ {{ $noop := .Page.Content }}
+
+<!-- Getting the map from the page's store  -->
+{{- $pageApiReferenceLinksMap := $.Page.Store.Get "pageApiReferenceLinksMap" -}} 
+
+<!-- Checking if "pageApiReferenceLinksMap" is not nil or empty -->
+{{- if and $pageApiReferenceLinksMap (ne (len $pageApiReferenceLinksMap) 0) -}}
+
+    <!-- Retrieving the "kind" parameter from the shortcode -->
+    {{- $kindParam := .Get "kind" -}}
+
+    <!-- Checking if "kind" parameter is provided -->
+    {{- if $kindParam -}}
+        <!-- Accessing the specific API reference "kind" from the map -->
+        {{ $apiRefPageLink   := index $pageApiReferenceLinksMap $kindParam}}
+        {{- printf "%s" $apiRefPageLink   | safeHTML -}}
+
+    {{- else -}} <!-- If "kind" parameter is not provided -->
+        <ul class="api-reference-links">
+            {{- range $kind, $apiRefPageLink := $pageApiReferenceLinksMap -}}
+                <li>{{- printf "%s" $apiRefPageLink   | safeHTML -}}</li>
+            {{- end -}}
+        </ul>
+    {{- end -}}
+    
+{{- end -}}
