Merge pull request #26151 from feloy/feloy-api-reference-links

api-reference shortcode + script to test links

content/en/docs/contribute/style/hugo-shortcodes/index.md

@@ -83,6 +83,33 @@ You can also include a full definition:
 which renders as:
 {{< glossary_definition term_id="cluster" length="all" >}}
 
+## Links to API Reference
+
+You can link to a page of the Kubernetes API reference using the `api-reference` shortcode, for example to the {{< api-reference page="workload-resources/pod-v1" >}} reference:
+
+```
+{{</* api-reference page="workload-resources/pod-v1" */>}}
+```
+
+The content of the `page` parameter is the suffix of the URL of the API reference page.
+
+
+You can link to a specific place into a page by specifying an `anchor` parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}} reference or the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}} section of the page:
+
+```
+{{</* api-reference page="workload-resources/pod-v1" anchor="PodSpec" */>}}
+{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" */>}}
+```
+
+
+You can change the text of the link by specifying a `text` parameter, for example by linking to the {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}} section of the page:
+
+```
+{{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" */>}}
+```
+
+
+
 ## Table captions
 
 You can make tables more accessible to screen readers by adding a table caption. To add a [caption](https://www.w3schools.com/tags/tag_caption.asp) to a table, enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.

layouts/shortcodes/api-reference.html

@@ -0,0 +1,7 @@
+{{ $base := "docs/reference/kubernetes-api" }}
+{{ $pageArg := .Get "page" }}
+{{ $anchorArg := .Get "anchor" }}
+{{ $textArg := .Get "text" }}
+{{ $page := site.GetPage "page" (printf "%s/%s" $base $pageArg) }}
+{{ $metadata := $page.Params.api_metadata }}
+<a href="{{ $page.URL }}{{if $anchorArg}}#{{ $anchorArg }}{{end}}">{{if $textArg}}{{ $textArg }}{{else if $anchorArg}}{{ $anchorArg }}{{else}}{{ $metadata.kind }}{{end}}</a>

scripts/linkchecker.py

@@ -35,6 +35,8 @@
 #   + /docs/bar                : is a redirect entry, or
 #   + /docs/bar                : is something we don't understand
 #
+# + {{ < api-reference page="" anchor="" ... > }}
+# + {{ < api-reference page="" > }}
 
 import argparse
 import glob
@@ -72,7 +74,8 @@ ARGS = None
 RESULT = {}
 # Cached redirect entries
 REDIRECTS = {}
-
+# Cached anchors in target pages
+ANCHORS = {}
 
 def new_record(level, message, target):
     """Create new checking record.
@@ -330,6 +333,44 @@ def check_target(page, anchor, target):
     msg = "Link may be wrong for the anchor [%s]" % anchor
     return new_record("WARNING", msg, target)
 
+def check_anchor(target_page, anchor):
+    """Check if an anchor is defined in the target page
+
+    :param target_page: The target page to check
+    :param anchor: Anchor string to find in the target page
+    """
+    if target_page not in ANCHORS:
+        try:
+            with open(target_page, "r") as f:
+                data = f.readlines()
+        except Exception as ex:
+            print("[Error] failed in reading markdown file: " + str(ex))
+            return
+        content = "\n".join(strip_comments(data))
+        anchor_pattern1 = r"<a name=\"(.*?)\""
+        regex1 = re.compile(anchor_pattern1)
+        anchor_pattern2 = r"{#(.*?)}"
+        regex2 = re.compile(anchor_pattern2)
+        ANCHORS[target_page] = regex1.findall(content) + regex2.findall(content)
+    return anchor in ANCHORS[target_page]
+
+def check_apiref_target(target, anchor):
+    """Check a link to an API reference page.
+
+    :param target: The link target string to check
+    :param anchor: Anchor string from the content page
+    """
+    base = os.path.join(ROOT, "content", "en", "docs", "reference", "kubernetes-api")
+    ok = check_file_exists(base + "/", target)
+    if not ok:
+        return new_record("ERROR", "API reference page not found", target)
+
+    if anchor is None:
+        return
+
+    target_page = os.path.join(base, target)+".md"
+    if not check_anchor(target_page, anchor):
+        return new_record("ERROR", "Anchor not found in API reference page", target+"#"+anchor)
 
 def validate_links(page):
     """Find and validate links on a content page.
@@ -355,6 +396,27 @@ def validate_links(page):
         r = check_target(page, m[0], m[1])
         if r:
             records.append(r)
+
+    # searches for pattern: {{< api-reference page="" anchor=""
+    apiref_pattern = r"{{ *< *api-reference page=\"([^\"]*?)\" *anchor=\"(.*?)\""
+    regex = re.compile(apiref_pattern)
+
+    matches = regex.findall(content)
+    for m in matches:
+        r = check_apiref_target(m[0], m[1])
+        if r:
+            records.append(r)
+
+    # searches for pattern: {{< api-reference page=""
+    apiref_pattern = r"{{ *< *api-reference page=\"([^\"]*?)\""
+    regex = re.compile(apiref_pattern)
+
+    matches = regex.findall(content)
+    for m in matches:
+        r = check_apiref_target(m, None)
+        if r:
+            records.append(r)
+
     if len(records):
         RESULT[page] = records