refactor: improve documentation link generation for capabilities

Author: alkaline-0

docs/website/tools/constants.py

@@ -29,23 +29,31 @@
 CAPABILITIES_TABLE_HEADER = "| Feature | Value | More |\n"
 
 SELECTED_CAPABILITIES_ATTRIBUTES = {
-    "preferred_loader_file_format", # /docs/dlt-ecosystem/file-formats
-    "supported_loader_file_formats", # /docs/dlt-ecosystem/file-formats
-    "preferred_staging_file_format", # /docs/dlt-ecosystem/file-formats
-    "supported_staging_file_formats", # /docs/devel/dlt-ecosystem/file-formats
-    "has_case_sensitive_identifiers", # /docs/general-usage/naming-convention#case-sensitive-and-insensitive-destinations
-    "supported_merge_strategies", # /docs/general-usage/merge-loading#merge-strategies
-    "supported_replace_strategies", # /docs/general-usage/full-loading#the-truncate-and-insert-strategy
-    "supports_tz_aware_datetime", # /docs/general-usage/schema#handling-of-timestamp-and-time-zones
-    "supports_naive_datetime", # /docs/general-usage/schema#handling-of-timestamp-and-time-zones
-    "sqlglot_dialect", # /docs/general-usage/dataset-access/dataset
-    "preferred_table_format", # /docs/dlt-ecosystem/table-formats
-    "supported_table_formats", # /docs/dlt-ecosystem/table-formats
+    "preferred_loader_file_format",
+    "supported_loader_file_formats",
+    "preferred_staging_file_format",
+    "supported_staging_file_formats",
+    "has_case_sensitive_identifiers",
+    "supported_merge_strategies",
+    "supported_replace_strategies",
+    "supports_tz_aware_datetime",
+    "supports_naive_datetime",
+    "sqlglot_dialect",
+    "preferred_table_format",
+    "supported_table_formats",
 }
 
 CAPABILITIES_DOC_LINK_PATTERNS = [
-    ("_formats", "../file-formats/"),
-    ("_strategies", "../../general-usage/merge-loading#merge-strategies"),
+    ("table", "../table-formats/"),
+    ("file_format", "../file-formats/"),
+    ("merge", "../../general-usage/merge-loading#merge-strategies"),
+    ("replace", "../../general-usage/full-loading#the-truncate-and-insert-strategy"),
+    ("time", "../../general-usage/schema#handling-of-timestamp-and-time-zones"),
+    ("dialect", "../../general-usage/dataset-access/dataset"),
+    (
+        "identifier",
+        "../../general-usage/naming-convention#case-sensitive-and-insensitive-destinations",
+    ),
 ]
 
 CAPABILITIES_DATA_TYPES_DOC_LINK = "[Data types](../../general-usage/schema#data-types)"

docs/website/tools/preprocess_destination_capabilities.py

@@ -74,15 +74,33 @@ def _format_value(value: Any) -> str:
 
 def _generate_doc_link(attr_name: str) -> str:
     """Generate documentation link based on attribute name pattern."""
-    for pattern, link in CAPABILITIES_DOC_LINK_PATTERNS:
-        if attr_name.endswith(pattern):
-            section_name = (
-                link.strip("/").split("/")[-1].split("#")[0].replace("-", " ").capitalize()
-            )
-            return f"[{section_name}]({link})"
+    lower = attr_name.lower()
+    for key, link in CAPABILITIES_DOC_LINK_PATTERNS:
+        if key in lower:
+            return _format_doc_link_for_key(key, link)
+
+    # Fallback to data types link when nothing matches
     return CAPABILITIES_DATA_TYPES_DOC_LINK
 
 
+def _format_doc_link_for_key(key: str, link: str) -> str:
+    """Format the markdown link for a capability mapping key and link.
+
+    Centralizes any human-friendly label overrides.
+    """
+    if key == "merge":
+        return f"[Merge strategy]({link})"
+    if key == "replace":
+        return f"[Truncate-and-insert strategy]({link})"
+    if key == "time":
+        return f"[Timestamps and Timezones]({link})"
+    if key == "dialect":
+        return f"[Dataset access]({link})"
+
+    section_name = link.strip("/").split("/")[-1].split("#")[0].replace("-", " ").capitalize()
+    return f"[{section_name}]({link})"
+
+
 def _is_relevant_capability(attr_name: str, value: Any) -> bool:
     """Check if capability should be included in table."""
     if value is None or attr_name not in SELECTED_CAPABILITIES_ATTRIBUTES: