Skip to content

Commit 60ca7a3

Browse files
dipesh-rawatdipesh-rawat
committed
Add mechanism to generate API reference links
1 parent 7c1f91a commit 60ca7a3

File tree

6 files changed

+107
-0
lines changed

6 files changed

+107
-0
lines changed

‎data/i18n/en/en.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33

44
# For "and", see [conjunction_1]
55

6+
[api_reference_title]
7+
other = "API reference"
8+
69
[auto_generated_edit_notice]
710
other = "(auto-generated page)"
811

‎layouts/docs/list.html

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717
{{ partial "docs/top-section-page" (dict "ctx" $ "page" $ ) }}
1818
{{- else -}}
1919
{{ partial "docs/content-page" (dict "ctx" $ "page" $ ) }}
20+
<!-- Partial "docs/api-reference-links" determines API reference links for 'partial/page-meta-links.html' -->
21+
{{ partial "docs/api-reference-links" $ }}
2022
{{- end -}}
2123
{{ else }}
2224
<h1>{{ .Title }}</h1>

‎layouts/docs/single.html

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
{{ define "main" }}
22
<div class="td-content">
33
{{ partial "docs/content-page" (dict "ctx" . "page" .) }}
4+
<!-- Partial "docs/api-reference-links" determines API reference links for 'partial/page-meta-links.html' -->
5+
{{ partial "docs/api-reference-links" . }}
46
</div>
57
{{ end }}
68
{{ define "hero-more" }}

‎layouts/partials/docs/api-reference-links.html

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
<!-- Define slice to store API reference links -->
2+
{{- $apiReferenceMetaLinks := slice -}}
3+
{{- $apiReferenceText := T "api_reference_title" -}}
4+
5+
<!-- Clear exisiting $.Store values -->
6+
{{ $.Store.Delete "apiReferenceMetaLinks" }}
7+
{{ $.Store.Delete "pageApiReferenceLinksMap" }}
8+
9+
<!-- Check if 'api_metadata' is an empty interface slice
10+
(Used for excluding auto-generated files and their localized versions) -->
11+
{{- $ignoreCondition := (printf "%T" .Page.Params.api_metadata | eq "[]interface {}") -}}
12+
13+
<!-- Check if 'api-metadata' exists in the front-matter of the file -->
14+
{{- if and .Page.Params.api_metadata $ignoreCondition (not .Page.Params.simple_list) -}}
15+
16+
<!-- Loop through each api_metadata entry -->
17+
{{- range $metadata := .Page.Params.api_metadata -}}
18+
<!-- Extract API metadata -->
19+
{{- $apiVersion := $metadata.apiVersion -}}
20+
{{- $kind := $metadata.kind -}}
21+
{{- $version := $apiVersion -}}
22+
{{- $linkText := $metadata.override_link_text | default $kind -}}
23+
24+
<!-- Get all sections under the specified directory -->
25+
{{- $apiRefBaseDir := "docs/reference/kubernetes-api/" -}}
26+
{{- $apiRefSections := site.GetPage "section" $apiRefBaseDir -}}
27+
28+
<!-- Loop through sections -->
29+
{{- range $apiRefSection := $apiRefSections.Sections -}}
30+
{{- $apiRefDir := $apiRefSection.RelPermalink -}}
31+
{{- $apiReferenceFiles := site.GetPage $apiRefDir -}}
32+
33+
<!-- Loop through API reference files -->
34+
{{- range $apiRefFile := $apiReferenceFiles.RegularPages -}}
35+
{{- $apiRefFileDirPath:= printf "/%s" $apiRefFile.File.Dir -}}
36+
37+
{{- if and (ne $apiRefFile.Section "") (in $apiRefFileDirPath $apiRefDir) -}}
38+
<!-- Check if the file's metadata matches -->
39+
{{- with $apiRefFile.Params.api_metadata -}}
40+
{{- if and (eq .kind $kind) (eq .apiVersion $version) -}}
41+
<!-- If the file's metadata matches, add link to variable -->
42+
{{- $link := printf "<a class='api-reference-page-link' href='%s'>%s %s</a>" $apiRefFile.Permalink $linkText $apiReferenceText -}}
43+
{{- $apiReferenceMetaLinks = $apiReferenceMetaLinks | append $link -}}
44+
<!-- Add to the map -->
45+
{{- $.Store.SetInMap "pageApiReferenceLinksMap" $kind $link -}}
46+
{{- end -}}
47+
{{- end -}}
48+
{{- end -}}
49+
{{- end -}}
50+
{{- end -}}
51+
{{- end -}}
52+
{{- end -}}
53+
54+
{{- if gt (len $apiReferenceMetaLinks) 0 -}}
55+
<!-- Store $apiReferenceMetaLinks for meta links in 'partials/page-meta-links.html' -->
56+
{{ $.Store.Add "apiReferenceMetaLinks" $apiReferenceMetaLinks }}
57+
{{- end -}}
58+

‎layouts/partials/page-meta-links.html

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,16 @@
2323
{{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL }}
2424
{{ $newPageURL := printf "%s/new/%s?%s" $gh_repo $gh_repo_path $newPageQS }}
2525

26+
<!-- Accessing API Reference links from "layouts/api-reference-links.html" -->
27+
{{- $apiReferenceMetaLinks := $.Store.Get "apiReferenceMetaLinks" -}}
28+
{{- if $apiReferenceMetaLinks -}}
29+
<!-- Loop through the API reference links -->
30+
{{- range $apiReferenceMetaLinks -}}
31+
{{- $apiRefPageLink := . -}}
32+
{{- $apiRefPageLink | replaceRE "<a([^>]*)>" "<a$1><i class=\"fa fa-code fa-fw\"></i> " | safeHTML -}}
33+
{{- end -}}
34+
{{- end -}}
35+
2636
{{ if not (.Param "auto_generated") }}
2737
<a href="{{ $editURL }}" target="_blank"><i class="fa fa-edit fa-fw"></i> {{ T "post_edit_this" }}</a>
2838
{{- if .HasShortcode "thirdparty-content" -}}

‎layouts/shortcodes/page-api-reference.html

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<!-- This shortcode shows API reference links based on metadata in the page's front matter -->
2+
3+
<!-- Call the partial template "docs/api-reference-links" to determine the API reference links -->
4+
{{ partial "docs/api-reference-links" page }}
5+
6+
<!-- "noop" (“no operation”) statement to let content render and store sync -->
7+
{{ $noop := .Page.Content }}
8+
9+
<!-- Getting the map from the page's store -->
10+
{{- $pageApiReferenceLinksMap := $.Page.Store.Get "pageApiReferenceLinksMap" -}}
11+
12+
<!-- Checking if "pageApiReferenceLinksMap" is not nil or empty -->
13+
{{- if and $pageApiReferenceLinksMap (ne (len $pageApiReferenceLinksMap) 0) -}}
14+
15+
<!-- Retrieving the "kind" parameter from the shortcode -->
16+
{{- $kindParam := .Get "kind" -}}
17+
18+
<!-- Checking if "kind" parameter is provided -->
19+
{{- if $kindParam -}}
20+
<!-- Accessing the specific API reference "kind" from the map -->
21+
{{ $apiRefPageLink := index $pageApiReferenceLinksMap $kindParam}}
22+
{{- printf "%s" $apiRefPageLink | safeHTML -}}
23+
24+
{{- else -}} <!-- If "kind" parameter is not provided -->
25+
<ul class="api-reference-links">
26+
{{- range $kind, $apiRefPageLink := $pageApiReferenceLinksMap -}}
27+
<li>{{- printf "%s" $apiRefPageLink | safeHTML -}}</li>
28+
{{- end -}}
29+
</ul>
30+
{{- end -}}
31+
32+
{{- end -}}

0 commit comments

Comments
 (0)