From a92f447478914639c15aee392cd11dd3c38ac970 Mon Sep 17 00:00:00 2001
From: Emmanuel Garette <egarette@silique.fr>
Date: Wed, 15 Oct 2025 09:53:54 +0200
Subject: [PATCH] feat: can document a variable for a specified identifier

---
 src/rougail/output_doc/utils.py | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/src/rougail/output_doc/utils.py b/src/rougail/output_doc/utils.py
index e1ac36bc9..ed76139cb 100644
--- a/src/rougail/output_doc/utils.py
+++ b/src/rougail/output_doc/utils.py
@@ -222,6 +222,7 @@ class CommonFormater:
         self,
         informations: dict,
         modified_attributes: dict,
+        force_identifiers: Optional[str],
     ) -> str:
         ret_paths = []
         path = informations["path"]
@@ -237,6 +238,8 @@ class CommonFormater:
             new = []
         if "identifiers" in informations:
             for identifier in informations["identifiers"]:
+                if force_identifiers and identifier != force_identifiers:
+                    continue
                 path_ = calc_path(path, self, identifier)
                 if identifier in new:
                     path_ = self.underline(path_)
@@ -299,7 +302,7 @@ class CommonFormater:
                         informations = value["informations"]
                         msg.append(self.namespace_to_title(informations, ori_level))
                         msg.append(self.family_informations())
-                        msg.extend(self.display_paths(informations, {}))
+                        msg.extend(self.display_paths(informations, {}, None))
                         msg.append(self.after_family_paths())
                         msg.append(
                             self.property_to_string(informations, {}, {})[1] + ENTER
@@ -327,7 +330,7 @@ class CommonFormater:
         """manage namespace family"""
         return self.title(
             _('Variables for "{0}"').format(
-                self.get_description("family", informations)
+                self.get_description("family", informations, {}, None)
             ),
             level,
         )
@@ -337,14 +340,14 @@ class CommonFormater:
 
     def family_to_string(self, informations: dict, level: int) -> str:
         """manage other family type"""
-        msg = [self.title(self.get_description("family", informations), level)]
+        msg = [self.title(self.get_description("family", informations, {}, None), level)]
         helps = informations.get("help")
         if helps:
             for help_ in helps:
                 msg.append(self.display_family_help(help_.strip()))
         msg.append(self.family_informations())
         msg.append(
-            self.join(self.display_paths(informations, {})) + self.after_family_paths()
+            self.join(self.display_paths(informations, {}, None)) + self.after_family_paths()
         )
         calculated_properties = []
         msg.append(
@@ -392,13 +395,13 @@ class CommonFormater:
         return self.stripped(self.join(datas))
 
     def get_description(
-        self, type_: str, informations: dict, modified_attributes: dict = {}
+        self, type_: str, informations: dict, modified_attributes: dict, force_identifiers: Optional[str]
     ) -> str():
         def _get_description(description, identifiers, delete=False, new=[]):
             if "{{ identifier }}" in description:
                 if type_ == "variable":
                     identifiers_text = display_list(
-                        [self.italic(i[-1]) for i in identifiers], separator="or"
+                        [self.italic(i[-1]) for i in identifiers if not force_identifiers or i == force_identifiers], separator="or"
                     )
                     description = description.replace(
                         "{{ identifier }}", identifiers_text
@@ -406,6 +409,8 @@ class CommonFormater:
                 else:
                     d = []
                     for i in identifiers:
+                        if force_identifiers and i != force_identifiers:
+                            continue
                         new_description = description.replace(
                             "{{ identifier }}", self.italic(i[-1])
                         )
@@ -442,12 +447,12 @@ class CommonFormater:
 
     # VARIABLE
     def variable_to_string(
-        self, informations: dict, table_datas: list, modified_attributes: dict = {}
+        self, informations: dict, table_datas: list, modified_attributes: dict = {}, force_identifiers: Optional[str]=None
     ) -> None:
         """Manage variable"""
         calculated_properties = []
         multi, first_column = self.variable_first_column(
-            informations, calculated_properties, modified_attributes
+            informations, calculated_properties, modified_attributes, force_identifiers
         )
         table_datas.append(
             [
@@ -457,7 +462,8 @@ class CommonFormater:
                         informations,
                         calculated_properties,
                         modified_attributes,
-                        multi=multi,
+                        multi,
+                        force_identifiers,
                     )
                 ),
             ]
@@ -468,13 +474,14 @@ class CommonFormater:
         informations: dict,
         calculated_properties: list,
         modified_attributes: Optional[dict],
+        force_identifiers: Optional[str],
     ) -> list:
         """Collect string for the first column"""
         multi, properties = self.property_to_string(
             informations, calculated_properties, modified_attributes
         )
         first_col = [
-            self.join(self.display_paths(informations, modified_attributes)),
+            self.join(self.display_paths(informations, modified_attributes, force_identifiers)),
             properties,
         ]
         self.columns(first_col)
@@ -486,13 +493,14 @@ class CommonFormater:
         calculated_properties: list,
         modified_attributes: dict,
         multi: bool,
+        force_identifiers: Optional[str],
     ) -> list:
         """Collect string for the second column"""
         second_col = []
         #
         if "description" in informations:
             description = self.get_description(
-                "variable", informations, modified_attributes
+                "variable", informations, modified_attributes, force_identifiers,
             )
             second_col.append(description)
         #