Set up system of code examples and details for message documentation (#5934)

1 files changed, 72 insertions, 1 deletions

diff --git a/doc/exts/pylint_messages.py b/doc/exts/pylint_messages.py
index 7f910918f..0f9ac35de 100644
--- a/doc/exts/pylint_messages.py
+++ b/doc/exts/pylint_messages.py
@@ -23,6 +23,8 @@ PYLINT_BASE_PATH = Path(__file__).resolve().parent.parent.parent
 PYLINT_MESSAGES_PATH = PYLINT_BASE_PATH / "doc" / "messages"
 """Path to the messages documentation folder."""
 
+PYLINT_MESSAGES_DATA_PATH = PYLINT_BASE_PATH / "doc" / "data" / "messages"
+"""Path to the folder with data for the messages documentation."""
 
 MSG_TYPES_DOC = {k: v if v != "info" else "information" for k, v in MSG_TYPES.items()}
 
@@ -32,6 +34,10 @@ class MessageData(NamedTuple):
     id: str
     name: str
     definition: MessageDefinition
+    good_code: str
+    bad_code: str
+    details: str
+    related_links: str
 
 
 MessagesDict = Dict[str, List[MessageData]]
@@ -47,6 +53,54 @@ def _register_all_checkers_and_extensions(linter: PyLinter) -> None:
     initialize_extensions(linter)
 
 
+def _get_message_data(data_path: Path) -> Tuple[str, str, str, str]:
+    """Get the message data from the specified path."""
+    good_code, bad_code, details, related = "", "", "", ""
+
+    if not data_path.exists():
+        return good_code, bad_code, details, related
+
+    if (data_path / "good.py").exists():
+        with open(data_path / "good.py", encoding="utf-8") as file:
+            file_content = file.readlines()
+            indented_file_content = "".join("  " + i for i in file_content)
+            good_code = f"""
+**Correct code:**
+
+.. code-block:: python
+
+{indented_file_content}"""
+
+    if (data_path / "bad.py").exists():
+        with open(data_path / "bad.py", encoding="utf-8") as file:
+            file_content = file.readlines()
+            indented_file_content = "".join("  " + i for i in file_content)
+            bad_code = f"""
+**Problematic code:**
+
+.. code-block:: python
+
+{indented_file_content}"""
+
+    if (data_path / "details.rst").exists():
+        with open(data_path / "details.rst", encoding="utf-8") as file:
+            file_content_string = file.read()
+            details = f"""
+**Additional details:**
+
+{file_content_string}"""
+
+    if (data_path / "related.rst").exists():
+        with open(data_path / "related.rst", encoding="utf-8") as file:
+            file_content_string = file.read()
+            related = f"""
+**Related links:**
+
+{file_content_string}"""
+
+    return good_code, bad_code, details, related
+
+
 def _get_all_messages(
     linter: PyLinter,
 ) -> Tuple[MessagesDict, OldMessagesDict]:
@@ -72,8 +126,20 @@ def _get_all_messages(
         "information": defaultdict(list),
     }
     for message in linter.msgs_store.messages:
+        message_data_path = (
+            PYLINT_MESSAGES_DATA_PATH / message.symbol[0] / message.symbol
+        )
+        good_code, bad_code, details, related = _get_message_data(message_data_path)
+
         message_data = MessageData(
-            message.checker_name, message.msgid, message.symbol, message
+            message.checker_name,
+            message.msgid,
+            message.symbol,
+            message,
+            good_code,
+            bad_code,
+            details,
+            related,
         )
         messages_dict[MSG_TYPES_DOC[message.msgid[0]]].append(message_data)
 
@@ -108,6 +174,11 @@ def _write_message_page(messages_dict: MessagesDict) -> None:
 
 *{message.definition.description}*
 
+{message.good_code}
+{message.bad_code}
+{message.details}
+{message.related_links}
+
 Created by ``{message.checker}`` checker
 """
                 )