From 3afd641543846c0da2d279adfbd750131b0177b6 Mon Sep 17 00:00:00 2001
From: Konstantin Chupin <kchupin@nebius.com>
Date: Thu, 7 Dec 2023 18:50:13 +0100
Subject: [PATCH] Add ability to process link in AMM MD docs generator

---
 .../dl_attrs_model_mapper_doc_tools/main.py   | 35 +++++++++++++++++--
 .../render_units.py                           | 11 +++---
 2 files changed, 39 insertions(+), 7 deletions(-)

diff --git a/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/main.py b/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/main.py
index 9d292df49..8acce9324 100644
--- a/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/main.py
+++ b/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/main.py
@@ -4,6 +4,7 @@
     Sequence,
     Type,
 )
+import urllib.parse
 
 import attr
 import yaml
@@ -25,9 +26,11 @@
     AmmOperation,
     AmmOperationExample,
 )
+from dl_attrs_model_mapper_doc_tools.md_link_extractor import process_links
 from dl_attrs_model_mapper_doc_tools.render_units import (
     ClassDoc,
     DocHeader,
+    DocLink,
     DocSection,
     DocText,
     DocUnit,
@@ -51,8 +54,34 @@ class Docs:
     _dedicated_class_docs: list[ClassDoc] = attr.ib(factory=list)
     _operations: list[tuple[AmmOperation, OperationDoc]] = attr.ib(factory=list)
 
+    _process_doc_links: bool = attr.ib(default=False)
+    _doc_links_map: dict[str, str] = attr.ib(factory=dict[str, str])
+
+    def adopt_doc_link(self, doc_link: DocLink) -> Optional[DocLink]:
+        parsed_href = urllib.parse.urlparse(doc_link.href)
+        if parsed_href.scheme != "visdocs":
+            return None
+
+        if doc_link.href not in self._doc_links_map:
+            raise ValueError(f"Mapping for visualization docs URL is not registered: {doc_link.href}")
+        return DocLink(text=doc_link.text, href=self._doc_links_map[doc_link.href])
+
+    def handle_text_from_spec(self, m_txt: Optional[MText]) -> Optional[DocText]:
+        if not self._process_doc_links:
+            return DocText(m_txt) if m_txt else None
+
+        if m_txt is None:
+            return None
+
+        en_txt: Optional[str] = m_txt.en
+        if en_txt is None:
+            return None
+
+        return DocText(process_links(en_txt, self.adopt_doc_link))
+
     def field_to_doc_lines(self, field: AmmField, path: Sequence[str]) -> Sequence[FieldLine]:
         cp = field.common_props
+        description: Optional[DocText] = self.handle_text_from_spec(field.common_props.description)
 
         if isinstance(field, AmmScalarField):
             scalar_type = field.scalar_type
@@ -71,7 +100,7 @@ def field_to_doc_lines(self, field: AmmField, path: Sequence[str]) -> Sequence[F
                         type_text=type_text,
                         nullable=cp.allow_none,
                         required=cp.required,
-                        description=field.common_props.description,
+                        description=description,
                     )
                 )
             ]
@@ -86,7 +115,7 @@ def field_to_doc_lines(self, field: AmmField, path: Sequence[str]) -> Sequence[F
                 type_ref=nested_schema_doc_file_path,
                 nullable=cp.allow_none,
                 required=cp.required,
-                description=field.common_props.description,
+                description=description,
             )
             if nested_schema_doc_file_path is not None:
                 return [main_line]
@@ -107,7 +136,7 @@ def field_to_doc_lines(self, field: AmmField, path: Sequence[str]) -> Sequence[F
                     type_text="list",
                     nullable=cp.allow_none,
                     required=cp.required,
-                    description=field.common_props.description,
+                    description=description,
                 ),
                 *self.field_to_doc_lines(field.item, next_path),
             ]
diff --git a/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/render_units.py b/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/render_units.py
index e3b9ddf71..ad196393d 100644
--- a/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/render_units.py
+++ b/lib/dl_attrs_model_mapper_doc_tools/dl_attrs_model_mapper_doc_tools/render_units.py
@@ -261,7 +261,7 @@ class FieldLine(DocUnit):
     nullable: bool
     required: bool
 
-    description: Optional[MText] = None
+    description: Optional[DocText] = None
     type_ref: Optional[str] = None
 
     def _get_type_md(self, render_ctx: RenderContext) -> str:
@@ -286,10 +286,13 @@ def get_table_header(self) -> DocTableHeader:
     def render_md(self, render_ctx: RenderContext) -> Sequence[str]:
         path = ".".join(f"`{part}`" for part in self.path)
 
+        description_txt: str = ""
+        description = self.description
+        if description is not None:
+            description_txt = "\n".join(description.render_md(render_ctx))
+
         return [
-            f"{path}"
-            f" | {self._get_type_md(render_ctx)}"
-            f" | {render_ctx.localized_m_text(self.description) or ''}".rstrip(" ").replace("\n", "<br>")
+            f"{path}" f" | {self._get_type_md(render_ctx)}" f" | {description_txt}".rstrip(" ").replace("\n", "<br>")
         ]